Contributing
The engine stays dialect-agnostic because every dialect maps to and from the shared canonical model. Adding an endpoint does not require pairwise converters for existing dialects.
Local setup
Prerequisites: Node ≥ 22.12 and pnpm 12 .
git clone https://github.com/JoaoPedroAS51/rosetta-date.git
cd rosetta-date
pnpm install| Script | Purpose |
|---|---|
pnpm dev | Build the library, then rebuild on source changes. |
pnpm build | Emit ESM modules, types, and source maps to dist/. |
pnpm playground | Build the library, then serve the playground and watch library changes. |
pnpm playground:build | Build the library and playground. |
pnpm docs:dev | Serve the documentation site. |
pnpm docs:build | Build the documentation site and search index. |
pnpm typecheck | Type-check the package without emitting. |
pnpm lint / pnpm lint:fix | Lint, and autofix, with the antfu config. |
pnpm test | Run the suite once. |
pnpm test:watch | Watch the source suites. |
pnpm test:unit | Run unit tests. |
pnpm test:endpoints | Run endpoint conformance, matrix, and round-trip tests. |
pnpm test:types | Check source type assertions. |
pnpm test:coverage | Run unit and endpoint tests with coverage, gated at 100%. |
pnpm test:dist | Build, then check plain-Node imports, package metadata, and exports resolution. |
pnpm test:types:dist | Build, then check the published declarations. |
pnpm test:package | Build, then run both artifact checks in parallel. |
Adding a dialect or library
To add a dialect, register it in src/dialects/registry.ts; to add a library, register it in
src/libraries/registry.ts and give it a libraryDeltas entry in test/fixtures/oracle.ts. A dialect in an
existing syntax family (delimited or directive) is pure data: pick its syntax and map its
tokens. A grammar that needs a new family adds one strategy module under src/core/syntax/ and one
member to the TokenSyntax union; the parser and renderer stay untouched.
The cross-endpoint suites read a hand-written oracle, test/fixtures/oracle.ts, that maps each
canonical to the endpoint’s primary spelling. A new dialect joins them with an expectations entry;
TypeScript requires one for every registered dialect.
Then update the documentation so the new dialect or library is discoverable. Keep these pages in sync by hand:
- Canonical Vocabulary: only if the new dialect or library needs a canonical field that does not exist yet; add the new member here, following the naming grammar below.
- Dialects: add a row to the index and a page for the new dialect (grammar, literals, aliases, caveats), plus a column in Token Mapping.
- Libraries: add a row to the index and a page for the new library (its
supportssubset and anyextendstokens). - API Reference: list the new export under its entrypoint.
Adding a canonical field
Most dialects and libraries reuse existing canonical fields. Add one only when a token expresses a meaning no member covers. Canonical values follow this grammar:
field/style[/qualifier...]field: the date component (month,hour,week-of-year, …).style: how it is represented (numeric,2-digit,ordinal,wide, …).qualifier(optional, repeatable): refines the basefield/style; its absence is the default form. Examples:iso(ISO week rules), the hour cycleh11/h12/h23/h24,standalone(grammatical context), and presentation refinements such asspace-padded(fill) andlower(case).
The member name is the PascalCase of the value’s segments, so name and value stay in lockstep:
week-of-year/ordinal/iso ↔ WeekOfYearOrdinalIso, month/wide/standalone ↔ MonthWideStandalone.
Qualifier order is part of a value’s identity, so each meaning has exactly one string and dialects
never disagree on a spelling. Order qualifiers by a fixed precedence: identity qualifiers that change
the rendered value (iso, the hour cycle, standalone) come first, then presentation qualifiers
that only change its surface (space-padded, lower). A blank-padded 24-hour is
hour/2-digit/h23/space-padded, never hour/2-digit/space-padded/h23.
Prefer refining an existing field/style with a qualifier over inventing a parallel field. This
keeps related meanings grouped and lets conversions share the base. Adding a member is a minor,
additive change; renaming or removing one is breaking.
TSDoc conventions
Use a consistent TSDoc structure for dialect and library exports.
Dialect TSDoc documents only the grammar it defines:
Scope: the supported token grammar.Literals: how literal text is represented.Rendering: how primary mappings are chosen.Case sensitivity: only when token case changes meaning.@see: official specs or token references.
Avoid mentioning concrete libraries in dialect TSDoc unless the behavior belongs to the dialect itself.
Library TSDoc documents the rendering target:
Base grammar: the dialect used by the library.Extensions: tokens added on top of the base grammar.Support model: whethersupportsis omitted or defines a subset.Runtime behavior: only for runtime requirements outside conversion logic.@see: official library docs.
Wrap code identifiers, plugin names, token names, and package names in backticks.
CI runs lint, typecheck, test:types, test:coverage, and test:package on every pull request. Record user-facing
changes with a changeset:
pnpm changesetTesting
Tests live in packages/rosetta-date/test/, outside src/, and import the package by name
(rosetta-date, rosetta-date/dialects, …), which Vitest and TypeScript alias to the source. Each
folder is a Vitest project:
| Folder | Project | Scope |
|---|---|---|
unit/ | unit | One unit’s behavior, in a tree that mirrors src/, plus mechanics the oracle cannot express (unsupported-token reasons, handler context, adjacency) |
endpoints/ | endpoints | Conformance, the conversion matrix, and round trips across every built-in dialect and library |
types/ | types | *.test-d.ts type tests of the public API, grouped by subject |
The endpoints suites derive from the oracle in test/fixtures/oracle.ts (each dialect’s
expectations, plus each library’s libraryDeltas). An oracle entry gives an endpoint conformance,
totality, matrix, and round-trip coverage. Tests reach internals by relative path only when the
public API has no equivalent.
Run pnpm test for all three projects, or select pnpm test:unit, pnpm test:endpoints, or
pnpm test:types. pnpm test:coverage enforces the 100% threshold for unit and endpoint tests;
type assertions do not contribute to runtime coverage.
pnpm test:package builds the library, then runs two checks in parallel: test:types:dist checks
type assertions against the published declarations, and test:dist checks a plain-Node import of
every entrypoint (test/artifact/smoke.mjs), package metadata with
publint in strict mode, and exports resolution with
Are the Types Wrong? . Both commands
can also be run separately from the repository root; Turbo builds the library first.
License
MIT © João Pedro Antunes Silva.