Skip to content

feat: add DateTime.UnixNanos - #9870

Closed
lloydrichards wants to merge 1 commit into
Effect-TS:mainfrom
lloydrichards:feat/unix-nanos
Closed

lloydrichards wants to merge 1 commit into
Effect-TS:mainfrom
lloydrichards:feat/unix-nanos

Conversation

@lloydrichards

@lloydrichards lloydrichards commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Type

  • Feature

Description

Another piece for the VirtualFileSystem work, for the attention of @fubhy.

This adds DateTime.UnixNano, a branded bigint for exact nanoseconds since the Unix epoch. It follows DateTime’s existing layout, with top-level functions such as unixNanoFromSeconds and unixNanoToDateTime. Existing DateTime APIs stay unchanged.

Conversions reject precision loss by default. Explicit "truncate" rounds toward zero:

DateTime.unixNanoFromSeconds(1.0000000009)
// Failure: PrecisionLoss

DateTime.unixNanoFromSeconds(1.0000000009, { precision: "truncate" })
// Success: 1000000000n

Values can exceed DateTime’s supported range. Conversion to Date or DateTime.Utc checks the original nanoseconds against that range before handling precision.

Checked conversions return Result with InvalidInput, OutOfRange, or PrecisionLoss. Schema.UnixNano validates values, with separate schemas for conversion reasons and errors.

Open to suggestions on the name and API.

Related

@changeset-bot

changeset-bot Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 27977f2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 33 packages
Name Type
effect Patch
@effect/opentelemetry Patch
@effect/vitest Patch
@effect/ai-anthropic Patch
@effect/ai-cloudflare Patch
@effect/ai-openai-compat Patch
@effect/ai-openai Patch
@effect/ai-openrouter Patch
@effect/ai-typesafe Patch
@effect/atom-react Patch
@effect/atom-solid Patch
@effect/atom-vue Patch
@effect/platform-browser Patch
@effect/platform-bun Patch
@effect/platform-deno Patch
@effect/platform-node-shared Patch
@effect/platform-node Patch
@effect/sql-clickhouse Patch
@effect/sql-d1 Patch
@effect/sql-libsql Patch
@effect/sql-mssql Patch
@effect/sql-mysql2 Patch
@effect/sql-pg Patch
@effect/sql-pglite Patch
@effect/sql-sqlite-bun Patch
@effect/sql-sqlite-do Patch
@effect/sql-sqlite-node Patch
@effect/sql-sqlite-react-native Patch
@effect/sql-sqlite-wasm Patch
@effect/docgen Patch
@effect/doctest Patch
@effect/graphql-generator Patch
@effect/openapi-generator Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@lloydrichards lloydrichards changed the title feat: add DateTIme.UnixNanos feat: add DateTime.UnixNanos Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name Current Size Previous Size Difference
arbitrary-combinators.ts 39.28 KB 39.28 KB 0.00 KB (0.00%)
basic.ts 7.15 KB 7.15 KB 0.00 KB (0.00%)
batching.ts 11.03 KB 11.03 KB 0.00 KB (0.00%)
brand.ts 6.83 KB 6.83 KB 0.00 KB (0.00%)
cache.ts 11.46 KB 11.46 KB 0.00 KB (0.00%)
config.ts 22.70 KB 22.70 KB 0.00 KB (0.00%)
differ.ts 21.83 KB 21.83 KB 0.00 KB (0.00%)
http-client.ts 26.26 KB 26.26 KB 0.00 KB (0.00%)
http-router.ts 36.57 KB 36.57 KB 0.00 KB (0.00%)
logger.ts 11.84 KB 11.84 KB 0.00 KB (0.00%)
metric.ts 9.38 KB 9.38 KB 0.00 KB (0.00%)
optic.ts 7.04 KB 7.04 KB 0.00 KB (0.00%)
pubsub.ts 15.91 KB 15.91 KB 0.00 KB (0.00%)
queue.ts 12.70 KB 12.70 KB 0.00 KB (0.00%)
schedule.ts 11.71 KB 11.71 KB 0.00 KB (0.00%)
schema-bigdecimal.ts 13.95 KB 13.95 KB 0.00 KB (0.00%)
schema-binary.ts 40.89 KB 40.89 KB 0.00 KB (0.00%)
schema-class.ts 21.48 KB 21.48 KB 0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts 32.56 KB 32.56 KB 0.00 KB (0.00%)
schema-representation-roundtrip.ts 27.83 KB 27.83 KB 0.00 KB (0.00%)
schema-string-transformation.ts 15.20 KB 15.20 KB 0.00 KB (0.00%)
schema-string.ts 12.20 KB 12.20 KB 0.00 KB (0.00%)
schema-template-literal.ts 16.14 KB 16.14 KB 0.00 KB (0.00%)
schema-toArbitrary.ts 38.80 KB 38.80 KB 0.00 KB (0.00%)
schema-toCodeDocument.ts 26.01 KB 26.01 KB 0.00 KB (0.00%)
schema-toCodecJson.ts 20.76 KB 20.76 KB 0.00 KB (0.00%)
schema-toEquivalence.ts 20.90 KB 20.90 KB 0.00 KB (0.00%)
schema-toFormatter.ts 21.00 KB 21.00 KB 0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts 26.00 KB 26.00 KB 0.00 KB (0.00%)
schema-toRepresentation.ts 21.08 KB 21.08 KB 0.00 KB (0.00%)
schema.ts 20.68 KB 20.68 KB 0.00 KB (0.00%)
stm.ts 14.04 KB 14.04 KB 0.00 KB (0.00%)
stream.ts 10.26 KB 10.26 KB 0.00 KB (0.00%)

@fubhy

fubhy commented Oct 24, 2026

Copy link
Copy Markdown
Member

@effect-bot

@fubhy
fubhy requested a review from effect-bot October 24, 2026 04:59
@fubhy fubhy added the vfs label Oct 24, 2026
@effect-bot

Copy link
Copy Markdown
Contributor

I recommend deferring this PR until VirtualFileSystem has a concrete consumer of nanosecond timestamps, rather than taking over the implementation now. The need is plausible, but the consumer should determine the public API.

The main design concern is the amount of API being committed to before that integration exists. This adds a separate branded timestamp, numeric precision modes, a conversion error type and schemas for those errors inside the millisecond-based DateTime module. Before landing that surface, we should establish how the filesystem will use it and how it fits with Clock.currentTimeNanos and Duration. Naming and fallible conversions should also follow the existing epoch-based DateTime and branded-bigint conventions.

I would leave the current implementation unchanged for now. To resume, bring a concrete filesystem call site that needs nanosecond precision, including the required range and behavior when converting to milliseconds. Then reassess the smallest useful API and reuse this PR if it is still suitable. This is a recommendation to park the takeover, not a request for a speculative rewrite.

@lloydrichards lloydrichards mentioned this pull request Oct 26, 2026
1 task done
@fubhy

fubhy commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

@effect-bot this might be good for protobuf too (which uses nanosecond granularity by default as well)

@lloydrichards

lloydrichards commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor Author

@effect-bot this might be good for protobuf too (which uses nanosecond granularity by default as well)

what did you end up with in protobuf in the end?

@lloydrichards

Copy link
Copy Markdown
Contributor Author

closing in favor of an issue #10674 as I move back to development on effect-vfs

This branch is waiting to be deployed

1 waiting deployment
fork — 27977f2d Waiting Oct 23, 2026 by lloydrichards via approval-gate #23052
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants