@curly-message/parser 1.0.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 G.A.W.Group, s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,417 @@
+# @curly-message/parser
+
+The JavaScript implementation of the
+[Curly Message Format](https://github.com/curly-message/spec).
+
+```json
+{
+  "greeting": "Hello, {{name; default:Guest;}}!",
+  "inbox": "You have {{count:number;}} {{count; 1:message; default:messages;}}."
+}
+```
+
+```
+greeting  { name: 'Alice' }  ->  "Hello, Alice!"
+greeting  {}                 ->  "Hello, Guest!"
+inbox     { count: 1 }       ->  "You have 1 message."
+inbox     { count: 1234 }    ->  "You have 1,234 messages."
+```
+
+A placeholder is written on one line: a `{{` and a `}}` with a line terminator
+anywhere between them are text rather than a placeholder, and escaping the
+terminator does not make them one. A placeholder that names no key — `{{}}`,
+`{{ }}` — is a placeholder still, and resolves through the fallback chain.
+
+Placeholders may carry a modifier (`:number`, `:date`, `:ago`, `:currency`, or
+one of the comparisons `eq`, `ne`, `lt`, `lte`, `gt`, `gte`), a set of options,
+and a `default`. Locale-dependent formatting is delegated to `Intl`; the
+package itself has no runtime dependencies. A modifier that cannot produce a
+result — a locale the host rejects, a custom modifier that throws — resolves
+the placeholder to its `default` rather than raising, and so does a value that
+no conversion turns into text. Neither is silent: containment keeps the failure
+out of the caller's render path, and a report is how the caller hears about it
+anyway. A placeholder naming a modifier the parser does not know resolves to
+its `default` and is reported as well; it is never run as a comparison instead.
+A comparison that declares no options has been asked to select from nothing —
+the inline `default` is the fallback itself rather than something to select, so
+`{{v:eq; default:D}}` declares none either. It resolves to the fallback chain,
+as it always did, and reports `missing-options`. That is a defect in how the
+placeholder was written, so it reports whether or not the payload carries the
+key. The six names are the format's comparisons while the format's own
+modifier answers to them: a host that registers its own `eq` has replaced the
+comparison, and whether its modifier needs options is that modifier's business,
+so `{{v:eq}}` over that registration reports nothing. A placeholder naming no
+key has nothing to compare, so `{{:eq}}` is no selection and reports nothing;
+`{{:zz}}` still reports the modifier nobody registered.
+Given no locale the formatting modifiers resolve to the empty string, not to
+the fallback chain: a declared default does not stand in for a locale nobody
+supplied. A caller that passes none and a caller that passes the empty string
+resolve alike; one that passes a locale the host then rejects has supplied one,
+and takes the fallback chain like any other formatting failure. The empty
+string is reported as `missing-locale`, whose origin is the payload: a locale
+nobody supplied is a defect in what the caller passed rather than in the
+message that was written.
+
+Given a locale, each formatting modifier reads its value as a particular kind
+of number, and a value that is not one resolves the placeholder to its
+`default` and is reported as `failed-modifier`, like any other result a
+modifier could not produce. Its origin is the payload too: the value, the props
+and the locale a modifier is handed are the caller's, and so is a
+`customModifiers` entry that raised, so none of it is a defect in the message
+that was written. The kind each reads:
+
+| Modifier | Value |
+| --- | --- |
+| `number` | a number |
+| `date` | milliseconds since the Unix epoch, or text the host can parse as a date |
+| `ago` | a signed millisecond delta relative to now, negative for the past |
+| `currency` | a number, multiplied by the `ratio` property below |
+
+Empty text and text that is only whitespace are none of these, whatever the
+host's own numeric conversion makes of them: `{{v:number}}` over `{ v: '' }`
+takes the fallback chain rather than formatting a zero, and `{{v:date}}` over
+the same value takes it rather than formatting the epoch.
+
+## Usage
+
+```js
+import { createParser } from '@curly-message/parser';
+
+const { resolve } = createParser();
+
+resolve('Hello, {{name; default:Guest;}}!', { payload: { name: 'Alice' }, locale: 'en' });
+// -> 'Hello, Alice!'
+```
+
+`createParser(options?)` returns a parser whose `resolve(message, context?)`
+takes the four inputs resolution is defined over, plus the message's own key:
+
+| Context | Meaning |
+| --- | --- |
+| `payload` | The values the placeholders name, or the configuration of one — see [Payload](#payload). Its `default` key is the message-wide fallback. |
+| `props` | Per-call formatting options handed to the modifiers, keyed by modifier name. A payload entry layers over them. |
+| `locale` | The locale the locale-dependent modifiers format for. |
+| `key` | The message's identifier. A missing message resolves to the payload's `default`, and to this where the payload carries none, echoed as the caller spelled it. |
+
+A message that no conversion describes is a message that does not exist:
+resolution steps past it to the payload's `default` and then to the key, and
+reports nothing, because a message nobody wrote is not a defect. The link it
+steps to is a payload value like any other, so one that is read and cannot be
+described is reported.
+
+The key is where that chain ends, and it is not text the format resolves over.
+A key shaped like a placeholder is echoed rather than resolved, an escape
+sequence inside one stays as it was spelled, and nothing behind the key is read
+a second time. It still becomes text, because `resolve` answers with text.
+
+`options` carries `customModifiers`, `modifierDefaults` and `onReport`. Nothing
+else is read, and the package has no runtime dependencies — locale-dependent
+formatting is delegated to `Intl`.
+
+`customModifiers` registers modifiers by name, over the built-in ones, so a
+name it carries is a name a message may write, and so is a name the parser
+holds a modifier under already. What it registers has to be a modifier: an
+entry that cannot be called registers none, so it takes no name of its own and
+does not shadow the built-in it names. Where nothing else answers to the name,
+a message writing it reads it as one nobody registered — `unknown-modifier`,
+the fallback chain; where a built-in answers to it, that built-in answers as it
+did, so `{ eq: 'text' }` costs a caller the name it wrote and nothing further.
+The types say as much, but a JavaScript caller reaches the table regardless.
+
+`onReport` is where diagnostics go. The parser writes to no channel of its own,
+so unset it reports nowhere; resolution still fails soft, it just does so
+silently. It is called with a `Report` describing what the parser could not do
+— `code`, the `origin` that code declares, an English `message` carrying
+nothing from the payload, the `limit` reached where the report is about one,
+the message's `key` where one was passed, and `text`, the source of the
+trouble: the placeholder that named it for `unknown-modifier`,
+`failed-modifier`, `missing-options`, `missing-locale` and
+`unserializable-value`, the output that would not settle for `pass-limit` and
+`output-limit`, the message as it was passed where the read that refused is of
+the call's own structure — a context entry, an entry of the option bag — and
+nothing at all where what could not be described is the chain the message
+itself resolves through. The last two name no placeholder, and a message that
+is not text carries none of itself either. `origin` says who fixes what `code`
+names — `'message'` for a defect in the message that was written, `'payload'`
+for one in what the caller passed, and `'limit'` for a bound this parser set.
+Every code declares one, and it ranks nothing: a report is no graver for coming
+from one of the three than from another. Only `text` derives from the payload.
+It is cut to 120 UTF-16 code units of what reached it — what a string's
+`length` counts — or one fewer where the last of them is the high half of a
+surrogate pair, so the cut never severs a character. A cut is marked with a
+trailing `...` of the parser's own, and the excerpt is escaped after that —
+quotes, backslashes, and every line terminator. So a cut excerpt arrives at
+122 code units at the shortest, one carrying something to escape arrives
+longer still, and no payload can forge a line where a report is written.
+
+Two guards bound resolution, and reaching either is what the two limit codes
+report. A payload value may name another placeholder, so interpolation runs
+again over what the last pass produced — at most **10 passes**, after which the
+output is returned with its remaining placeholders unresolved. And the output
+may not exceed **100000 UTF-16 code units** — what a string's `length` counts,
+so a character outside the Basic Multilingual Plane counts twice; a pass that
+would carry it past that stops, and the last output under the bound is what
+resolves. Both are what make
+a payload value that references or multiplies its own placeholder terminate
+rather than hang the caller.
+
+A third bound holds the conversion that feeds them. Turning a value into JSON
+follows a shared reference again every time it meets one, so a value naming the
+same child twice at each of twenty-four levels holds twenty-five objects and
+describes sixteen million leaves — no cycle anywhere, and nothing an output
+bound measured after the fact can prevent. So the walk stops after **100000
+nodes**, and the value is read as one no conversion describes: it falls through
+its fallback chain and reports as `unserializable-value`. That is what a single
+conversion may spend, and a resolution converts one value once however many
+placeholders name it, so what a resolution spends converting is bounded by the
+values it reaches rather than by the reads it makes of them. That covers the
+host's own conversion as well as the JSON walk, so a class instance whose
+`toString` runs host code runs it once for the resolution rather than once for
+each placeholder, and one that raises is not asked a second time. It covers a
+bigint as well, which runs no host code at all but converts to digits the
+engine works out afresh on every read. A value built afresh on each read — by
+a payload getter, or by a custom modifier — is a new value every time and is
+converted every time. Whether an entry is a wrapper is asked the same way:
+recognizing one enumerates the entry's own names, work that grows with the
+entry, so a resolution asks one entry once however many placeholders name it,
+and an entry that refuses the question is not asked again — though it reports
+at every placeholder that reads it.
+
+All three bounds belong to the call rather than to the parser, and a call is
+what a host begins by calling `resolve` again while one is running — from a
+custom modifier, from an `onReport` handler writing its diagnostic into a
+translated string, from a payload accessor, or from a value's own `toString`.
+Such a resolution counts its own passes, spends its own output and keeps its
+own record of what it has converted, so neither it nor the one around it can
+reach a bound the other owns, each report names the message its own call was
+resolving, and a value the two share is converted once for each of them.
+Nothing bounds how deep that goes: a modifier resolving a message that names
+it again recurses until the host's own stack runs out, which is contained like
+any other failure — the placeholder takes its fallback chain and `resolve`
+still answers with text.
+
+## Payload
+
+Everything the format carries is text. A payload value reaches a modifier, and
+the output, as text whatever type it was written at: a plain object and an
+array become JSON, and every other value becomes what the host makes of it, so
+a `Date`, a `RegExp` or a class instance reads as its own `toString` writes it.
+
+```
+{ v: 1234.5 }      ->  1234.5
+{ v: [1, 2] }      ->  [1,2]
+{ v: { a: 1 } }    ->  {"a":1}
+{ v: /re/g }       ->  /re/g
+```
+
+That conversion costs a `Date` its sub-second precision, because `String(date)`
+writes seconds: `{{v:date}}` over `new Date('2024-03-05T10:00:00.123Z')`
+renders the same instant with its milliseconds zeroed. The text is not numeric
+either, so `{{v:number}}`, `{{v:currency}}`, `{{v:ago}}`, `{{v:lt}}` and
+`{{v:gt}}` over a `Date` resolve to the fallback chain — the three formatting
+ones given a locale, because with none they resolve to the empty string
+whatever the value is. Pass a timestamp or an ISO string where a placeholder
+needs either.
+
+A payload entry may carry the value's own configuration — a wrapper — instead
+of the value itself:
+
+```js
+resolve('You have {{count:number}} points.', {
+  payload: {
+    count: { value: 1234.56, props: { number: { maximumFractionDigits: 1 } } },
+  },
+  locale: 'en',
+});
+// -> 'You have 1,234.6 points.'
+```
+
+An entry is a wrapper when it is a plain object that owns at least one key and
+every key it owns is `value`, `default` or `props`. An entry owning anything
+else is a value, wrapper-shaped or not: `{ value: 1, unit: 'kg' }` and `{}` are
+data and become JSON. Unwrapping happens once, so a wrapper's `value` is never
+read as a wrapper of its own, and a wrapper carrying no `value` falls back like
+a key the payload does not carry. The payload's own `default` is always a
+value.
+
+A placeholder resolves to its value wherever the payload carries one, and
+otherwise to the first of these that yields text:
+
+1. the wrapper's `default`
+2. the payload's `default`
+3. the `default` the placeholder declares
+4. the empty string
+
+A value no conversion describes — a structure that references itself, a getter
+that raises — is read as missing and falls through this chain, and so does any
+link in it. Anything the chain reads and could not convert is reported as
+`unserializable-value`; a link nothing reaches is never read, so it is never
+reported either.
+
+Every entry the parser reads is read as an own **enumerable** property: a
+payload key, a wrapper's, a `props` layer's, an entry of the modifier registry,
+and the call's own `payload`, `props`, `locale` and `key`. That is the rule the
+value conversion has always followed, so a property `Object.defineProperty`
+left hidden is not one the format carries anywhere — after
+`Object.defineProperty(payload, 'v', { value: 'V' })`, `{{v}}` resolves to its
+fallback chain, and a hidden `onReport` reports nowhere. A prototype somebody
+else wrote to supplies nothing at any of those reads either.
+
+A read that raises is an absence and a report wherever it sits, not only at a
+value. A `props` entry that refuses to be read leaves the layer beneath it
+standing and reports `unserializable-value` at the placeholder that needed it;
+`customModifiers`, `modifierDefaults` and the context's own entries are read
+once for the call, so a report about one names the text that went looking
+rather than a placeholder, and a `key` that is itself the entry that raised
+leaves the report naming no key.
+
+A modifier's answer becomes text by that same conversion, so an answer no
+conversion describes is read as missing and reported the same way, and the
+placeholder takes the chain. An answer that is nothing at all is an absent
+answer rather than one that could not be described: it takes the chain too, and
+says nothing.
+
+A modifier reaches the chain by reading its own `defaultValue`, which resolves
+at the moment of that read — running whatever host code the chain carries and
+reporting a link it cannot describe. A generic copy of a modifier's config is
+such a read, so a rest destructure, a spread or `JSON.stringify` walks a chain
+that a modifier taking the keys it needs by name leaves alone.
+
+Formatting options are keyed by modifier name, and their layers compose per
+property: the parser's `modifierDefaults`, then the `props` the call passes,
+then the wrapper's own `props`. Each layer overrides only the properties it
+names, so a layer cannot reset an earlier one: a property set to `undefined`
+names nothing, where one set to the host's null is named and null — a value,
+like zero — is what the modifier is handed. Only what a layer owns composes,
+and only under the name the placeholder wrote: what a layer holds under other
+names is not read for it. The object a modifier is handed owns every entry it
+is configured with and carries no prototype, so a prototype somebody else wrote
+to configures nothing.
+
+```
+modifierDefaults  { number: { maximumFractionDigits: 4, useGrouping: false } }
+call props        { number: { useGrouping: true } }
+wrapper props     { number: { maximumFractionDigits: 1 } }
+effective         { maximumFractionDigits: 1, useGrouping: true }  ->  1,234.6
+```
+
+A modifier is handed that composition under its own name and nothing else — the
+`effective` line is what `number` reads — so what one modifier is configured
+with never reaches the next, and a modifier nobody configured is handed an empty
+object rather than nothing. A modifier a host registers reads its properties the
+same way, `modifierDefaults` included, and the object it holds is the parser's
+own copy: writing into it reaches neither the next placeholder nor the caller.
+
+`number` formats at most two fraction digits when no layer names a maximum.
+That two is a default rather than a cap: a layer naming a
+`minimumFractionDigits` above it widens the default to reach it, the way
+`Intl.NumberFormat` widens its own.
+
+`currency` formats in the currency style whatever a layer names as the style:
+that style is the modifier rather than one of the options it layers. It
+multiplies its value by a `ratio` property first, defaulting to 1, so a payload
+carrying minor units renders as major ones.
+
+`ago` takes the unit to count in from a `format` property holding a unit name,
+in the singular or the plural: `second`, `minute`, `hour`, `day`, `week`,
+`month` and `year` are the rungs of the ladder it climbs. Its `auto`, which is
+what a layer naming none leaves in place, selects the unit from the magnitude
+of the delta instead. A `format` naming anything else — a unit `Intl` knows and
+this ladder does not climb, a rung spelled in another case — is a property the
+modifier cannot process: the placeholder takes its fallback chain and reports
+`failed-modifier`.
+
+`ratio` and `format` are the format's own properties rather than `Intl`'s, and
+both are read from the layers like every other property — a message cannot
+write either as an option.
+
+```
+{ v: 2 }           { currency: { currency: 'USD', ratio: 100 } }  ->  $200.00
+{ v: -172800000 }  { ago: {} }                                    ->  2 days ago
+{ v: -172800000 }  { ago: { format: 'hour' } }                    ->  48 hours ago
+```
+
+## Escaping
+
+The syntax reserves a colon, a semicolon, either brace, a backslash and
+whitespace. A backslash takes the structural meaning away from the character
+that follows it, and the rule is the same everywhere in a message — inside a
+placeholder and in the text around it alike.
+
+Whitespace means the twenty-five code points the specification enumerates, not
+whatever the host calls whitespace: a host's own class is defined over a
+Unicode category that has changed membership before.
+
+```
+Braces are written \{\{ like this \}\}      ->  "Braces are written {{ like this }}"
+Hello, {{first\ name; default:Guest}}!      ->  names the payload key "first name"
+{{count; 1:one\ ; default:none}}            ->  keeps the trailing space
+C:\\temp                                    ->  "C:\temp"
+```
+
+The rule reaches the braces themselves: a brace a backslash consumed is text,
+so it cannot be half of a delimiter. That is what lets a key end in a closing
+brace; one that starts no pair needs no escape.
+
+```
+\{{v}}      ->  "{{v}}"      text, whatever the payload carries
+\\{{v}}     ->  a backslash, then the placeholder {{v}}
+{{v\}}      ->  "{{v}}"      no closing pair, so the whole run is text
+{{v\}}}     ->  names the payload key "v}"
+{{v\\}}     ->  names the payload key "v\"
+{{a}b}}     ->  names the payload key "a}b"
+```
+
+Before anything the syntax does not reserve, a backslash is text itself, so a
+regular expression or a Windows path survives as typed: `\d+` resolves to
+`\d+`, and `C:\Users\name` to `C:\Users\name`.
+
+A payload value is read the same way, because a value may carry a placeholder
+of its own. A value that has to keep a backslash in front of a reserved
+character doubles it — `\\server\share` resolves to `\server\share`.
+
+Escape sequences are removed once, from the finished text, so the removal
+reaches the text a conversion produced as readily as the text a message was
+written in. The two characters JSON writes for a backslash are an escape
+sequence, and the removal takes one of them, so the JSON a plain object
+serializes to does not necessarily reach the output parsable as JSON.
+
+```
+{ v: { a: 'C:\U' } }    serializes to  {"a":"C:\\U"}  and renders  {"a":"C:\U"}
+```
+
+A modifier is unaffected, because it reads its value before the removal runs:
+one that parses a serialized object back reads the serialization the conversion
+produced. A caller that needs the result itself to parse passes the text it
+wants as an ordinary string value, with every backslash doubled.
+
+## Status
+
+**Unreleased, and the public surface is unstable.**
+
+Nothing here references a host framework: `resolve` takes the format's own
+inputs, and an adapter that presents this parser to a host library belongs in
+that host's own repository.
+
+This implementation satisfies every conformance level the specification
+defines: **Core**, **Intl** and **Extensions**. Section 2 asks an
+implementation to say so, because a level it does not satisfy changes what a
+message resolves to rather than merely what it can do — without Intl, `number`,
+`date`, `ago` and `currency` are modifier names nobody registered.
+
+The specification is normative — where this implementation and the
+specification disagree, this implementation is wrong.
+
+## Development
+
+```bash
+npm install
+npm test         # builds, typechecks, lints, then runs vitest
+npm run lint:fix # applies what the lint step only reports
+```
+
+Requires Node.js 22 or newer.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/// <reference lib="es2020.intl" />
+declare const eq: Modifier.T;
+declare const ne: Modifier.T;
+declare const lt: Modifier.T;
+declare const gt: Modifier.T;
+declare const lte: Modifier.T;
+declare const gte: Modifier.T;
+declare const number: Modifier.T<Modifier.NumberProperties>;
+declare const date: Modifier.T<Modifier.DateProperties>;
+declare const ago: Modifier.T<Modifier.AgoProperties>;
+declare const currency: Modifier.T<Modifier.CurrencyProperties>;
+
+declare const modifiers_ago: typeof ago;
+declare const modifiers_currency: typeof currency;
+declare const modifiers_date: typeof date;
+declare const modifiers_eq: typeof eq;
+declare const modifiers_gt: typeof gt;
+declare const modifiers_gte: typeof gte;
+declare const modifiers_lt: typeof lt;
+declare const modifiers_lte: typeof lte;
+declare const modifiers_ne: typeof ne;
+declare const modifiers_number: typeof number;
+declare namespace modifiers {
+  export { modifiers_ago as ago, modifiers_currency as currency, modifiers_date as date, modifiers_eq as eq, modifiers_gt as gt, modifiers_gte as gte, modifiers_lt as lt, modifiers_lte as lte, modifiers_ne as ne, modifiers_number as number };
+}
+
+declare const AGO_LADDER: readonly [{
+    readonly key: "second";
+    readonly multiplier: 1000;
+}, {
+    readonly key: "minute";
+    readonly multiplier: 60;
+}, {
+    readonly key: "hour";
+    readonly multiplier: 60;
+}, {
+    readonly key: "day";
+    readonly multiplier: 24;
+}, {
+    readonly key: "week";
+    readonly multiplier: 7;
+}, {
+    readonly key: "month";
+    readonly multiplier: number;
+}, {
+    readonly key: "year";
+    readonly multiplier: 12;
+}];
+
+/**
+ * A locale as it reaches resolution — an opaque identifier the modifiers hand
+ * to `Intl`. The format neither parses nor validates it.
+ */
+type Locale = string;
+/**
+ * Holds a position out of the inference the surrounding call does. A type
+ * parameter is decided where it is declared or where its own argument names it
+ * — never by a second position that merely has to agree with it.
+ */
+type Given<T> = [T][T extends any ? 0 : never];
+/**
+ * The branches of an all-optional bag that owns at least one of its keys: one
+ * per key, each requiring that key be present and leaving the rest optional.
+ * A key holding `undefined` is owned; the empty object owns none.
+ */
+type AtLeastOne<T> = {
+    [Key in keyof T]-?: Record<Key, T[Key]> & Omit<T, Key>;
+}[keyof T];
+/**
+ * A diagnostic the parser hands to its caller. The format does not specify a
+ * channel to report through, so the parser writes nowhere itself and describes
+ * what happened instead.
+ */
+type Report = {
+    /** What stopped resolution. */
+    code: 'unknown-modifier' | 'failed-modifier' | 'missing-options' | 'unserializable-value' | 'missing-locale' | 'pass-limit' | 'output-limit';
+    /**
+     * Which of the three the defect belongs to, and so who fixes it: the message
+     * that was written, what the caller passed, or a limit this parser set. Every
+     * code declares one. It ranks nothing — a report is no graver for coming from
+     * one of the three than from another.
+     */
+    origin: 'message' | 'payload' | 'limit';
+    /**
+     * The same in English. It is self-contained and carries nothing from the
+     * payload, so writing it anywhere is safe without further thought.
+     */
+    message: string;
+    /** The message's own key, where the caller passed one. */
+    key?: Parser.Key;
+    /** The limit that was reached, where the report is about one. */
+    limit?: number;
+    /**
+     * Where the trouble came from: the placeholder for a report about one, the
+     * output that would not settle for the two limits, the message as the caller
+     * wrote it where a read of the call's own structure refused — a context
+     * entry, an entry of the option bag — and nothing at all where what could
+     * not be described is the chain a message itself resolves through. The last
+     * two name no placeholder, and a message that is not text carries none of
+     * itself either. Truncated — a cut is marked with a trailing `...` of the
+     * parser's own — and with its line terminators escaped, so payload content
+     * cannot forge a line wherever this is written.
+     */
+    text: string;
+};
+declare namespace Modifier {
+    export type Key = string;
+    export type DefaultKeys = keyof typeof modifiers;
+    type AgoStep = (typeof AGO_LADDER)[number]['key'];
+    /**
+     * A unit `ago` can resolve to, read off the ladder it climbs rather than off
+     * `Intl`'s whole vocabulary: a `format` naming a unit the ladder does not
+     * climb is one the modifier cannot format with, so the placeholder takes the
+     * fallback chain and the failure is reported. Every step is accepted in the
+     * plural too, so a layer naming one may spell it either way.
+     */
+    export type AgoUnit = AgoStep | `${AgoStep}s`;
+    /**
+     * What a modifier of this name is handed: the properties composed under it,
+     * which is what the layers keyed by that name carry. The `*Props` type
+     * beside each is the layer itself — one name, holding those properties.
+     */
+    export type AgoProperties = Intl.RelativeTimeFormatOptions & {
+        format?: AgoUnit | 'auto';
+    };
+    export type AgoProps = {
+        ago?: AgoProperties;
+    };
+    export type DateProperties = Intl.DateTimeFormatOptions;
+    export type DateProps = {
+        date?: DateProperties;
+    };
+    export type NumberProperties = Intl.NumberFormatOptions;
+    export type NumberProps = {
+        number?: NumberProperties;
+    };
+    export type CurrencyProperties = Intl.NumberFormatOptions & {
+        ratio?: number;
+    };
+    export type CurrencyProps = {
+        currency?: CurrencyProperties;
+    };
+    export type DefaultProps = NumberProps & AgoProps & DateProps & CurrencyProps;
+    export type Props<T = DefaultProps> = T & DefaultProps;
+    export type ModifierOption = Record<'key' | 'value', string>;
+    /**
+     * A value's own configuration, standing in the payload where the value
+     * would. An entry is a wrapper only when it is a plain object that owns at
+     * least one key and every key it owns is one of these; an entry with a
+     * prototype of its own, one owning anything else, or one owning nothing at
+     * all, is a value, wrapper-shaped or not.
+     */
+    export type Wrapper<Value = any, CustomModifierProps = DefaultProps> = AtLeastOne<{
+        /** The value itself. A wrapper carrying none falls back like a missing key. */
+        value?: Value;
+        /** Tried before the payload's own `default` and before the inline one. */
+        default?: any;
+        /** Layered over the `props` the call passes, property by property. */
+        props?: Props<CustomModifierProps>;
+    }>;
+    /**
+     * A modifier is handed text and nothing else: a placeholder whose value is
+     * absent takes its fallback chain before any modifier is called, and that
+     * chain ends in the empty string.
+     *
+     * `OwnProps` is what this modifier's own name holds, because that
+     * composition is what it is handed; `CustomModifierProps` is the table that
+     * name sits in, which is what `parserOptions` is read under. A modifier
+     * registered through `customModifiers` is given both by the table it is
+     * registered in, so only one written down away from its table names them.
+     * The empty composition is the default, because that is what a name nobody
+     * configured holds.
+     */
+    export type T<OwnProps = {}, CustomModifierProps = DefaultProps> = (config: {
+        value: string;
+        /**
+         * The properties composed under this modifier's own name, layered from the
+         * implementation defaults up through the wrapper's own and copied, so a
+         * modifier that writes into what it was handed reaches neither the next
+         * placeholder nor the caller. A modifier nobody configured is handed an
+         * empty object.
+         */
+        props: OwnProps;
+        locale?: Locale;
+        parserOptions?: Parser.Options<Modifier.Key, CustomModifierProps>;
+        options: ModifierOption[];
+        /**
+         * The fallback chain, resolved by the read rather than before the modifier
+         * was called: reading it walks the wrapper's `default`, then the payload's,
+         * then the one the placeholder declared, runs whatever host code those
+         * links carry, and reports one no conversion describes. A generic copy of
+         * the config is such a read — a rest destructure, a spread,
+         * `JSON.stringify` — so a modifier with no use for the default takes the
+         * keys it needs by name.
+         */
+        defaultValue: string;
+    }) => any;
+    export type DefaultModifiers = typeof modifiers;
+    /**
+     * Modifiers by the name each answers to. A name the table declares
+     * properties for holds a modifier reading that slice; one it declares none
+     * for holds a modifier reading none by name. The slice reaches an entry
+     * through the names the table is typed with — the ones the factory infers
+     * from the table it is given, or the ones an annotation names — so a table
+     * or an option bag annotated without them types every entry, one under a
+     * built-in name included, as reading none.
+     */
+    export type CustomModifiers<K extends string = Key, ModifierProps = DefaultProps> = {
+        [Name in K]: Modifier.T<Name extends keyof Props<ModifierProps> ? NonNullable<Props<ModifierProps>[Name]> : {}, ModifierProps>;
+    };
+    export {  };
+}
+declare namespace Parser {
+    type OnReport = (report: Report) => void;
+    type Options<Key extends string = Modifier.Key, Props = Modifier.DefaultProps> = {
+        /**
+         * Modifiers registered by name, over the built-in ones. A name a message
+         * may write is one the parser holds a modifier under or one a host
+         * registered one under, so an entry that is not a modifier registers none:
+         * it takes no name of its own and shadows no built-in. The name then reads
+         * as one nobody registered where nothing else answers to it, and answers
+         * as it did where a built-in does.
+         */
+        customModifiers?: Modifier.CustomModifiers<Key, Props>;
+        /**
+         * The bottom formatting layer, keyed by modifier name. It carries the same
+         * names the call's own `props` does, host-defined modifiers included — a
+         * modifier a host can configure per call it can also give defaults.
+         */
+        modifierDefaults?: Modifier.Props<Given<Props>>;
+        /**
+         * Where diagnostics go. Unset, the parser reports nowhere — resolution
+         * still fails soft, it just does so silently.
+         */
+        onReport?: OnReport;
+    };
+    type PayloadDefault = {
+        [key in 'default']?: any;
+    };
+    /** What a payload carries under a key: the value, or its configuration. */
+    type PayloadEntry<Value = any, Props = Modifier.DefaultProps> = Value | Modifier.Wrapper<Value, Props>;
+    /**
+     * The values a message's placeholders name, plus `default` — the fallback
+     * for every key the payload does not carry.
+     *
+     * A value reaches a modifier as text: a plain object and an array become
+     * JSON, and anything else becomes what the host makes of it. An entry may
+     * instead be a `Modifier.Wrapper`, which configures the value it carries.
+     *
+     * A `Date` loses its sub-second precision to that conversion, and the text
+     * `String` writes for one is not numeric, so `number`, `currency`, `ago`,
+     * `lt` and `gt` over a `Date` resolve to the fallback chain — the three
+     * formatting ones given a locale, because with none they resolve to the
+     * empty string whatever the value is. A timestamp or an ISO string keeps
+     * both.
+     *
+     * A value passes through the same unescaping as the message around it: a
+     * backslash before a character the syntax reserves — `:`, `;`, `{`, `}`, a
+     * backslash, or whitespace — writes that character as text and is dropped
+     * itself, while a backslash before anything else is left as it is. So a
+     * value holding `\d+` arrives as typed, and one holding `\\server\share`
+     * resolves to `\server\share` unless each consumed backslash is doubled.
+     */
+    type Payload<T = any, Props = Modifier.DefaultProps> = [Exclude<keyof T, keyof PayloadDefault>] extends [never] ? Record<string, PayloadEntry<any, Props>> & PayloadDefault : {
+        [Key in keyof T]: PayloadEntry<T[Key], Props>;
+    } & PayloadDefault;
+    type Key = string;
+    type Value = any;
+    /**
+     * Everything resolution reads besides the message itself. `key` is the
+     * message's own identifier where the caller has one. A missing message
+     * resolves to the payload's own `default`, and to `key` where the payload
+     * carries none — the same chain a placeholder falls through, one level up.
+     */
+    type Context<P = PayloadDefault, M = Modifier.DefaultProps> = {
+        payload?: Payload<P, M>;
+        props?: Modifier.Props<M>;
+        locale?: Locale;
+        key?: Key;
+    };
+    type Resolve<C extends Parser.Context = Parser.Context> = (message: Value, context?: C) => string;
+    type T<C extends Parser.Context = Parser.Context> = {
+        /**
+         * Interpolates the message against the given context and returns the result.
+         */
+        resolve: Resolve<C>;
+    };
+    /**
+     * The payload type comes first: with no host config to carry it, the factory
+     * is where a caller declares what its messages expect.
+     */
+    type Factory = <Payload = {}, Props = {}, Key extends string = Modifier.Key>(options?: Parser.Options<Key, Props>) => Parser.T<Parser.Context<Payload & PayloadDefault, Props & Modifier.DefaultProps>>;
+}
+
+declare const createParser: Parser.Factory;
+
+export { type Locale, Modifier, Parser, type Report, createParser };

package/dist/index.js

@@ -0,0 +1,2 @@
+var Ae=Object.defineProperty;var Oe=(e,n)=>{for(var t in n)Ae(e,t,{get:n[t],enumerable:!0})};var U={};Oe(U,{ago:()=>Ve,currency:()=>$e,date:()=>Se,eq:()=>te,gt:()=>he,gte:()=>De,lt:()=>ge,lte:()=>Ne,ne:()=>ke,number:()=>Le});var le=[`
+`,"\r","\u2028","\u2029"],N=[{key:"second",multiplier:1e3},{key:"minute",multiplier:60},{key:"hour",multiplier:60},{key:"day",multiplier:24},{key:"week",multiplier:7},{key:"month",multiplier:4.333333333333333},{key:"year",multiplier:12}],Z=e=>`\\u${e.charCodeAt(0).toString(16).padStart(4,"0")}`,G=e=>!/[^\t\n\v\f\r\u0020\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]/.test(e),d=(e,n,t)=>{try{return n!==void 0&&e&&Object.prototype.propertyIsEnumerable.call(e,n)?e[n]:void 0}catch{t?.();return}},k=(e,n)=>{if(!e)return[];try{return Object.keys(e)}catch{return n?.(),[]}},M=(e,n,t)=>{let o=Object.create(null);return k(e,t).forEach(r=>{o[r]=d(e,r,t)}),k(n,t).forEach(r=>{let i=d(n,r,t);i!==void 0&&(o[r]=i)}),o},ee=(e,n)=>{let t=Object.create(null);return k(e,n).forEach(o=>{let r=d(e,o,n);typeof r=="function"&&(t[o]=r)}),t},l=class extends Error{constructor(t){super(t);this.code=t}code},pe=e=>{try{return e instanceof l?e.code:void 0}catch{return}},P=e=>{if(typeof e=="string"&&G(e))return;let n=+e;return Number.isFinite(n)?n:void 0},me=e=>{let n=P(e);if(n!==void 0)return n;let t=Date.parse(e);return Number.isNaN(t)?void 0:t};var W=(e,n)=>e?e.value:n.defaultValue,te=e=>{let{value:n,options:t=[]}=e,o=`${n}`.toLowerCase();return W(t.find(({key:r})=>`${r}`.toLowerCase()===o),e)},ke=e=>{let{value:n,options:t=[]}=e,o=`${n}`.toLowerCase();return W(t.find(({key:r})=>`${r}`.toLowerCase()!==o),e)},ye=(e,n)=>e.filter(({key:t})=>!Number.isNaN(+t)).sort((t,o)=>n(+t.key,+o.key)),ge=e=>{let{value:n,options:t=[]}=e,o=+n;return W(ye(t,(r,i)=>r-i).find(({key:r})=>o<+r),e)},he=e=>{let{value:n,options:t=[]}=e,o=+n;return W(ye(t,(r,i)=>i-r).find(({key:r})=>o>+r),e)},Ne=e=>te({value:e.value,props:e.props,options:e.options,get defaultValue(){return ge(e)}}),De=e=>te({value:e.value,props:e.props,options:e.options,get defaultValue(){return he(e)}}),D=e=>{if(e===void 0)throw new l("failed-modifier");return e},Le=e=>{let{value:n,props:t,locale:o=""}=e;if(!o)throw new l("missing-locale");let r=D(P(n)),i=Number(d(t,"minimumFractionDigits"))||0,s=K(d(t,"maximumFractionDigits"),Math.max(i,2));return new Intl.NumberFormat(o,M(t,{maximumFractionDigits:s})).format(r)},Se=e=>{let{value:n,props:t,locale:o=""}=e;if(!o)throw new l("missing-locale");let r=D(me(n));return new Intl.DateTimeFormat(o,M(t,void 0)).format(r)},K=(e,n)=>e===void 0?n:e,ne=(e="",n="")=>new RegExp(`^${e}s?$`).test(n),je=e=>e==="auto"||N.some(({key:n})=>ne(n,e)),Ce=e=>N.indexOf(N.find(({key:n})=>ne(n,e))),_e=e=>Math.sign(e)*Math.round(Math.abs(e)),Fe=(e,n)=>N.reduce(([t,o],{key:r,multiplier:i},s)=>{if(ne(o,n))return[t,o];if(!o||s===Ce(o)+1){let a=_e(t/i);if(!o||Math.abs(a)>=1||n!=="auto")return[a,r]}return[t,o]},[e,""]),Ve=e=>{let{value:n,locale:t="",props:o}=e;if(!t)throw new l("missing-locale");let r=D(P(n)),i=K(d(o,"numeric"),"auto"),s=K(d(o,"format"),"auto");if(!je(s))throw new l("failed-modifier");let a=Fe(r,s);return new Intl.RelativeTimeFormat(t,M(o,{numeric:i})).format(...a)},$e=e=>{let{value:n,locale:t="",props:o}=e;if(!t)throw new l("missing-locale");let r=D(P(n)),i=D(P(r*K(d(o,"ratio"),1)));return new Intl.NumberFormat(t,M(o,{style:"currency"})).format(i)};var Re=`[${le.map(Z).join("")}]`,be=new RegExp(Re),ve=new RegExp(Re,"g"),ze=(e,n)=>{for(let t=n+2;t<e.length;t+=1){let o=e[t];if(o==="\\"){if(be.test(e.charAt(t+1)))return;t+=1;continue}if(be.test(o)||o==="{"&&e.charAt(t+1)==="{")return;if(o==="}"&&e.charAt(t+1)==="}")return t+2}},re=(e,n)=>{for(let t=n;t<e.length;t+=1){if(e[t]==="\\"){t+=1;continue}if(e[t]!=="{"||e.charAt(t+1)!=="{")continue;let o=ze(e,t);if(o!==void 0)return[t,o]}},Ge=e=>typeof e=="string"&&!!re(e,0),Ke=/[:;{}\\]/,q=e=>typeof e=="string"?e.replace(/\\([\s\S])/g,(n,t)=>Ke.test(t)||G(t)?t:n):e,L=e=>{let n=-1,t=0;for(let o=0;o<e.length;o+=1){let r=e[o]==="\\"&&o+1<e.length;!r&&G(e[o])||(n<0&&(n=o),o+=r?1:0,t=o+1)}return n<0?"":e.slice(n,t)},oe=(e,n)=>{let t=[],o=0;for(let r=0;r<e.length;r+=1)e[r]==="\\"?r+=1:e[r]===n&&(t.push(e.slice(o,r)),o=r+1);return[...t,e.slice(o)]},Ee=e=>{if(!e||typeof e!="object")return!1;try{let n=Object.getPrototypeOf(e);return n===Object.prototype||n===null}catch{return!1}},We=e=>{let n=I;try{let t=JSON.stringify(e,(o,r)=>{if(n-=1,n<0)throw new RangeError("The value visits more nodes than a resolvable output can hold.");return r});return typeof t=="string"?t:void 0}catch{return}},Me=e=>{try{if(!Ee(e)&&!Array.isArray(e))return String(e)}catch{return}return We(e)},B=(e,n)=>e===void 0?void 0:e!==null&&(typeof e=="object"||typeof e=="function"||typeof e=="bigint")?(n.has(e)||n.set(e,Me(e)),n.get(e)):Me(e),ie=(e,n,t)=>{let o=B(e,t);return e!==void 0&&o===void 0&&n(),o},Ue=["value","default","props"],qe=(e,n,t)=>{if(!Ee(e))return!1;if(!n.has(e)){let r=!1,i=k(e,()=>{r=!0});n.set(e,r?void 0:!!i.length&&i.every(s=>Ue.includes(s)))}let o=n.get(e);return o===void 0&&t?.(),!!o},we=e=>!!e&&(typeof e=="object"||typeof e=="function"),Xe=(e,n,t)=>e.reduce((o,r)=>{let i=we(r)?d(r,n,t):void 0;return we(i)?M(o,i,t):o},Object.create(null)),Be=["eq","ne","lt","gt","lte","gte"],He=(e,n)=>Be.includes(e)&&n[e]===U[e],Je=({value:e,props:n,payload:t,parserOptions:o,modifiers:r,modifierDefaults:i,onReport:s,locale:a,key:c,conversions:w,wrappers:R})=>{let f=Object.keys(r),E=m=>{let[A,...S]=oe(m.slice(2,-2),";"),[j,...C]=oe(A,":"),de=L(j),_=de?q(de):void 0,y=()=>h("unserializable-value",m,c,s),H=d(t,_,y),F=_!=="default"&&qe(H,R,y)?H:void 0,Te=F?d(F,"value",y):H,V=[],J;S.forEach(g=>{let[b,...ce]=oe(g,":"),z=q(L(b)),fe=ce.length?L(ce.join(":")):L(b);z&&(J===void 0&&z==="default"&&(J=fe),z!=="default"&&V.push({key:z,value:fe}))});let Y=g=>ie(g,y,w),$=Y(Te),ue,Pe=_==="default"?()=>$:()=>Y(d(t,"default",y)),O=()=>(ue??=[()=>Y(d(F,"default",y)),Pe].reduce((g,b)=>g??b(),void 0)??J??"",ue),v=q(L(C.join(":"))),Q=!!v;if(Q&&!f.includes(v))return h("unknown-modifier",m,c,s),O();if(_!==void 0&&!V.length&&He(v,r)&&h("missing-options",m,c,s),$===void 0)return O();if(!Q&&!V.length)return $;let ae=Q?v:"eq",Ie=r[ae];try{let g=Xe([i,n,d(F,"props",y)],ae,y);return ie(Ie({value:$,options:V,props:g,get defaultValue(){return O()},locale:a,parserOptions:o}),y,w)??O()}catch(g){let b=pe(g)??"failed-modifier";return h(b,m,c,s),b==="missing-locale"?"":O()}},u=`${e}`,x=[],T=0,p=0;for(let m=re(u,p);m;m=re(u,p)){let[A,S]=m;if(A+T>I)return;let j=u.slice(A,S),C=E(j);if(x.push(u.slice(p,A),C),T+=C.length-j.length,p=S,p+T>I)return}return u.length+T>I?void 0:[...x,u.slice(p)].join("")},se=10,xe=ee(U),I=1e5,X=120,Ye=e=>e.slice(0,(e.codePointAt(X-1)??0)>65535?X-1:X),Qe=e=>JSON.stringify(e.length>X?`${Ye(e)}...`:e).slice(1,-1).replace(ve,Z),Ze={"unknown-modifier":"A placeholder named a modifier this parser does not know.","failed-modifier":"A modifier could not produce a result, so the placeholder took its fallback chain.","missing-options":"A comparison was given no options to select from, so the placeholder took its fallback chain.","unserializable-value":"A value could not become text, so resolution read it as missing.","missing-locale":"A formatting modifier was given no locale, so the placeholder resolved to the empty string.","pass-limit":`Interpolation stopped after ${se} passes. A payload value probably references its own placeholder.`,"output-limit":`Interpolation stopped before exceeding ${I} characters. A payload value probably multiplies its own placeholder.`},et={"unknown-modifier":void 0,"failed-modifier":void 0,"missing-options":void 0,"unserializable-value":void 0,"missing-locale":void 0,"pass-limit":se,"output-limit":I},tt={"unknown-modifier":"message","failed-modifier":"payload","missing-options":"message","unserializable-value":"payload","missing-locale":"payload","pass-limit":"limit","output-limit":"limit"},h=(e,n,t,o)=>{if(o)try{o({code:e,origin:tt[e],message:Ze[e],key:t,limit:et[e],text:Qe(n)})}catch{}},nt=({value:e,props:n,payload:t,parserOptions:o,modifiers:r,modifierDefaults:i,onReport:s,locale:a,key:c,conversions:w,wrappers:R})=>{let f=e;for(let E=0;Ge(f);E+=1){if(E===se){h("pass-limit",f,c,s);break}let u=Je({value:f,payload:t,props:n,parserOptions:o,modifiers:r,modifierDefaults:i,onReport:s,locale:a,key:c,conversions:w,wrappers:R});if(u===void 0){h("output-limit",f,c,s);break}f=u}return B(q(f),w)??""},dt=e=>({resolve:(n,t)=>{let o=d(e,"onReport"),r=typeof n=="string"?n:"",i=d(t,"key",()=>h("unserializable-value",r,void 0,o)),s=()=>h("unserializable-value",r,i,o),a=d(t,"payload",s),c=d(t,"props",s),w=d(t,"locale",s),R=d(e,"customModifiers",s),f=d(e,"modifierDefaults",s),E=R===void 0?xe:M(xe,ee(R,s)),u=()=>h("unserializable-value","",i,o),x=new Map,T=new Map,p=B(n,x)??ie(d(a,"default",u),u,x);return p===void 0?B(i,x)??"":nt({value:p,payload:a,props:c,parserOptions:e,modifiers:E,modifierDefaults:f,onReport:o,locale:w,key:i,conversions:x,wrappers:T})}});export{dt as createParser};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@curly-message/parser",
+  "version": "1.0.0-next.0",
+  "description": "JavaScript implementation of the Curly Message Format.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "pretest": "npm run build && npm run typecheck && npm run lint",
+    "test": "vitest run",
+    "build": "tsup",
+    "prepack": "npm run build",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint --fix .",
+    "prepare": "cd .. && simple-git-hooks js/.simple-git-hooks.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/curly-message/parsers.git",
+    "directory": "js"
+  },
+  "keywords": [
+    "curly-message",
+    "parser",
+    "i18n",
+    "internationalization",
+    "translations",
+    "interpolation"
+  ],
+  "author": "Jarda Svoboda",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/curly-message/parsers/issues"
+  },
+  "homepage": "https://github.com/curly-message/parsers/tree/main/js#readme",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^10.8.1",
+    "eslint-plugin-import-x": "^4.17.1",
+    "globals": "^17.11.0",
+    "simple-git-hooks": "^2.13.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.1.6",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.10"
+  }
+}