@evolu/common 8.0.0 → 8.2.0

package/dist/src/Type.js

@@ -90,7 +90,7 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
     throw new Error(`Expected ${name}.`, { cause: error });
 };
 /**
- * Creates localized copies of selected {@link Type | Types} for every locale.
+ * Localized copies of selected {@link Type} declarations for every locale.
  *
  * Each locale supplies one formatter for every Type that can own a formatted
  * error. Structural Types use their own formatter for structural failures and
@@ -341,6 +341,8 @@ const encoderSymbol =
 /*#__PURE__*/ globalThis.Symbol();
 const fromSymbol = 
 /*#__PURE__*/ globalThis.Symbol();
+const templateLiteralSyntaxSymbol = 
+/*#__PURE__*/ globalThis.Symbol();
 const mapRuntimeResult = (operation, map) => (value, options = firstValidationOptions) => map(operation(value, options), options);
 // `map` must return a fresh operation because this function can attach `.parent`.
 const mapRuntimeOperations = (operation, map) => {
@@ -600,7 +602,7 @@ export const Uint8Array = /*#__PURE__*/ objectTag("Uint8Array");
  */
 export const ArrayBuffer = /*#__PURE__*/ objectTag("ArrayBuffer");
 /**
- * Creates a {@link Type} for instances of one constructor.
+ * Instance {@link Type} for one constructor.
  *
  * Membership uses the intrinsic prototype chain, so subclasses are accepted,
  * equivalent constructors from other realms are rejected, and custom
@@ -644,6 +646,26 @@ export const instanceOf = (constructor) => {
  * primitive through `from.parent`. The expected value must have one exact
  * literal type. Validation uses `===`, so `-0` matches `0`.
  *
+ * In {@link templateLiteralParser}, use a string Literal Type when the literal
+ * should be decoded into the Output Tuple. Use a raw string when it should only
+ * frame the canonical string.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { literal } from "@evolu/common";
+ *
+ * const Ready = literal("ready");
+ *
+ * expectTypeOf<typeof Ready.Output>().toEqualTypeOf<"ready">();
+ * expectOk(Ready.fromUnknown("ready"), "ready");
+ * expectErr(Ready.fromUnknown("pending"), {
+ *   type: "Literal",
+ *   expected: "ready",
+ *   value: "pending",
+ * });
+ * ```
+ *
  * @group Unions
  */
 export const literal = (expected) => {
@@ -663,7 +685,10 @@ export const literal = (expected) => {
     const formatError = (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not strictly equal to the expected literal: ${globalThis.String(error.expected)}.`;
     return globalThis.Object.assign(parent
         ? createChildType("Literal", parent, validate, formatError)
-        : createRootType("Literal", validate, formatError), { expected: literalExpected });
+        : createRootType("Literal", validate, formatError), {
+        expected: literalExpected,
+        [templateLiteralSyntaxSymbol]: true,
+    });
 };
 /** @group Unions */
 export const Undefined = /*#__PURE__*/ literal(undefined);
@@ -692,7 +717,7 @@ export function union(...typesOrLiterals) {
         assertNonNullable(member);
         return member[encoderSymbol](value);
     };
-    return createTypeNode("Union", input, fromUnknown, (value) => members.some((member) => member.is(value)), validateOutput, from, to, getTypeIssues, { members });
+    return createTypeNode("Union", input, fromUnknown, (value) => members.some((member) => member.is(value)), validateOutput, from, to, getTypeIssues, { members, [templateLiteralSyntaxSymbol]: true });
 }
 const formatUnionError = () => "A value does not match any union member.";
 const createUnionValidation = (members, validateMember) => (value, options = firstValidationOptions) => {
@@ -714,7 +739,7 @@ const createUnionValidation = (members, validateMember) => (value, options = fir
     });
 };
 /**
- * Shorthand for passing a {@link Type} and `undefined` to {@link union}.
+ * Union {@link Type} containing the supplied Type and `undefined`.
  *
  * This does not make an object property optional. It changes only the values
  * accepted when the property is present.
@@ -723,13 +748,13 @@ const createUnionValidation = (members, validateMember) => (value, options = fir
  */
 export const undefinedOr = (type) => union(type, Undefined);
 /**
- * Shorthand for passing a {@link Type} and `null` to {@link union}.
+ * Union {@link Type} containing the supplied Type and `null`.
  *
  * @group Unions
  */
 export const nullOr = (type) => union(type, Null);
 /**
- * Shorthand for passing a {@link Type}, `null`, and `undefined` to {@link union}.
+ * Union {@link Type} containing the supplied Type, `null`, and `undefined`.
  *
  * @group Unions
  */
@@ -737,6 +762,407 @@ export const nullishOr = (type) => union(type, Null, Undefined);
 const isRuntimeUnionTypeNode = (type) => type.name === "Union" &&
     "members" in type &&
     globalThis.Array.isArray(type.members);
+/**
+ * Template literal {@link Type} for validation and parsing.
+ *
+ * Parses and creates structured strings.
+ *
+ * Accepts the same template parts as {@link templateLiteral}: fixed string
+ * literals and Types canonically encoded as strings. Instead of keeping Output
+ * as a string, fixed literals define the framing and Output is a readonly Tuple
+ * of the decoded Type parts. `to` encodes that Tuple back into the canonical
+ * string represented by the parent Type. At least one Type part is required.
+ *
+ * When every capture uses identity encoding, the parent Output is the exact
+ * TypeScript template literal type. A transforming capture makes it nominal;
+ * create such strings with `to` or validate them with the parent Type.
+ *
+ * Deterministic framing is a core correctness guarantee. It preserves
+ * reversibility and keeps capture boundaries unambiguous. Different capture
+ * Tuples must never encode to the same string. The parser provides predictable
+ * parsing without pathological backtracking and decodes each capture once, so
+ * adversarial input cannot trigger exponential parser work. Fixed-width captures
+ * may be adjacent, but only one variable-width capture is allowed. Declarations
+ * that could join UTF-16 surrogate halves across parts are rejected during
+ * construction.
+ *
+ * Keep capture unions reasonably small to avoid excessive compiler work.
+ *
+ * TypeScript template literal types can describe a fixed number of digit
+ * positions, but not an arbitrarily long sequence of digits. Such grammars use
+ * branded Types such as {@link DecimalString}; `templateLiteralParser` preserves
+ * that exactness by requiring a validated branded capture when encoding.
+ *
+ * ### Example
+ *
+ * A template literal Type defines both a canonical string representation and
+ * the structured data decoded from it:
+ *
+ * ```ts
+ * import { templateLiteralParser, union } from "@evolu/common";
+ *
+ * const Language = union("en", "cs");
+ * const Region = union("US", "CZ");
+ *
+ * // Define a Type for "en-US" | "en-CZ" | "cs-US" | "cs-CZ".
+ * const SupportedLocale = templateLiteralParser(Language, "-", Region);
+ *
+ * // Output is the decoded language and region.
+ * type SupportedLocale = typeof SupportedLocale.Output;
+ * expectTypeOf<SupportedLocale>().toEqualTypeOf<
+ *   readonly ["en" | "cs", "US" | "CZ"]
+ * >();
+ *
+ * // The parent Output is the canonical locale string.
+ * type SupportedLocaleLiteral = typeof SupportedLocale.parent.Output;
+ * expectTypeOf<SupportedLocaleLiteral>().toEqualTypeOf<
+ *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ"
+ * >();
+ *
+ * // Parse an unknown string into structured data.
+ * const result = SupportedLocale.fromUnknown("cs-CZ");
+ * assert(result.ok);
+ * const locale = result.value;
+ * expectTypeOf(locale).toEqualTypeOf<SupportedLocale>();
+ * expect(locale).toEqual(["cs", "CZ"]);
+ * expectErr(SupportedLocale.fromUnknown("cs/CZ"), {
+ *   type: "TemplateLiteral",
+ *   value: "cs/CZ",
+ * });
+ *
+ * // Encode structured data into its canonical string.
+ * const localeLiteral = SupportedLocale.to(locale);
+ * expectTypeOf(localeLiteral).toEqualTypeOf<SupportedLocaleLiteral>();
+ * expect(localeLiteral).toBe("cs-CZ");
+ *
+ * // Validate a string configuration value.
+ * const configValue: unknown = "cs-CZ";
+ * assert(SupportedLocale.parent.is(configValue));
+ * expectTypeOf(configValue).toEqualTypeOf<SupportedLocaleLiteral>();
+ * expect(SupportedLocale.parent.is("fr-CZ")).toBe(false);
+ * ```
+ *
+ * `SupportedLocale` is structured data for application code.
+ * `SupportedLocaleLiteral` is its canonical representation for configuration
+ * and other APIs that require a string, such as URL parameters, environment
+ * variables, and storage keys.
+ *
+ * Use branded captures for strings that TypeScript template literal types
+ * cannot express exactly, such as arbitrary-length canonical decimals:
+ *
+ * ```ts
+ * import {
+ *   NonNegativeDecimalString,
+ *   templateLiteralParser,
+ * } from "@evolu/common";
+ *
+ * const DecimalText = templateLiteralParser(
+ *   "decimal:",
+ *   NonNegativeDecimalString,
+ * );
+ *
+ * // DecimalText.to requires a validated NonNegativeDecimalString.
+ * const zero = NonNegativeDecimalString.orThrow("0");
+ *
+ * expectOk(DecimalText.fromUnknown("decimal:0"), [zero]);
+ * expect(DecimalText.to([zero])).toBe("decimal:0");
+ * ```
+ *
+ * Capture Types (the Type arguments passed to `templateLiteralParser`) can use
+ * transformations to decode substrings into non-string data:
+ *
+ * ```ts
+ * import {
+ *   Int64FromInt64String,
+ *   templateLiteralParser,
+ * } from "@evolu/common";
+ *
+ * const ItemId = templateLiteralParser("item-", Int64FromInt64String);
+ * type ItemId = typeof ItemId.Output;
+ * type ItemIdLiteral = typeof ItemId.parent.Output;
+ *
+ * // Decode the string into structured data.
+ * const result = ItemId.fromUnknown("item-42");
+ * assert(result.ok);
+ * const itemId = result.value;
+ * expectTypeOf(itemId).toEqualTypeOf<ItemId>();
+ * expect(itemId).toEqual([42n]);
+ *
+ * // Encode the structured data into its canonical string.
+ * const itemIdLiteral = ItemId.to(itemId);
+ * expectTypeOf(itemIdLiteral).toEqualTypeOf<ItemIdLiteral>();
+ * expect(itemIdLiteral).toBe("item-42");
+ *
+ * // TypeScript cannot prove from the literal alone that "42" is a valid Int64 encoding.
+ * // @ts-expect-error Validate it with ItemId.parent or create it with ItemId.to.
+ * const invalidItemIdLiteral: ItemIdLiteral = "item-42";
+ * ```
+ *
+ * Fixed-width captures can be adjacent:
+ *
+ * ```ts
+ * import { templateLiteralParser, union } from "@evolu/common";
+ *
+ * const Digit = union("0", "1", "2", "3", "4", "5", "6", "7", "8", "9");
+ * const TwoDigits = templateLiteralParser(Digit, Digit);
+ * type TwoDigits = typeof TwoDigits.Output;
+ * type TwoDigitsLiteral = typeof TwoDigits.parent.Output;
+ *
+ * const twoDigits: TwoDigits = ["4", "2"];
+ * const twoDigitsLiteral: TwoDigitsLiteral = "42";
+ * // @ts-expect-error TwoDigitsLiteral requires exactly two digits.
+ * const threeDigitsLiteral: TwoDigitsLiteral = "123";
+ *
+ * expectOk(TwoDigits.from.parent(twoDigitsLiteral), twoDigits);
+ * expect(TwoDigits.to(twoDigits)).toBe(twoDigitsLiteral);
+ * ```
+ *
+ * TypeScript rejects multiple variable-width captures because their encoded
+ * boundaries would be ambiguous:
+ *
+ * ```ts
+ * import { String, templateLiteralParser } from "@evolu/common";
+ *
+ * // @ts-expect-error At most one Type capture can have a variable-width string representation.
+ * templateLiteralParser(String, ":", String);
+ * ```
+ *
+ * This restriction keeps encoding reversible: different capture Tuples must
+ * never produce the same string. A delimiter alone is not enough because it can
+ * also occur inside a capture. Some formats could provide stronger guarantees,
+ * such as captures that exclude a delimiter; support for those can be added
+ * when concrete use cases justify the additional framing rules.
+ *
+ * @group Template literals
+ */
+export const templateLiteralParser = (...parts) => createTemplateLiteralParserType(parts);
+const createTemplateLiteralParserType = (templateParts) => {
+    const captureTypes = templateParts.filter((part) => typeof part !== "string");
+    const runtimeCaptureTypes = captureTypes;
+    const output = tuple(...captureTypes);
+    const runtimeOutput = output;
+    const reflection = {
+        output,
+        parts: templateParts,
+        [templateLiteralSyntaxSymbol]: true,
+    };
+    const parse = compileTemplateLiteralParser(templateParts);
+    const decodeString = (value, options = firstValidationOptions) => {
+        const parseResult = parse(value);
+        if (!parseResult.ok)
+            return parseResult;
+        const outputResult = validateTupleItems(parseResult.value, runtimeCaptureTypes, (capture, value, captureOptions) => capture.fromUnknown(value, captureOptions), options, false);
+        return (outputResult.ok
+            ? outputResult
+            : err({
+                type: "TemplateLiteral",
+                outputError: outputResult.error,
+            }));
+    };
+    const encodeCaptures = (captures) => {
+        const encodedCaptures = runtimeOutput[encoderSymbol](captures);
+        let value = "";
+        let captureIndex = 0;
+        for (const part of templateParts) {
+            value +=
+                typeof part === "string" ? part : encodedCaptures[captureIndex++];
+        }
+        return value;
+    };
+    const canonicalizeString = (value, options) => {
+        const result = decodeString(value, options);
+        return result.ok ? ok(encodeCaptures(result.value)) : result;
+    };
+    const validateCanonicalString = (value, options = firstValidationOptions) => {
+        const stringResult = String.fromUnknown(value, options);
+        if (!stringResult.ok)
+            return stringResult;
+        const result = canonicalizeString(stringResult.value, options);
+        if (!result.ok || result.value === stringResult.value)
+            return result;
+        return err({ type: "TemplateLiteral", value: stringResult.value });
+    };
+    const getTypeIssues = (error, mode) => {
+        if (error.type !== "TemplateLiteral") {
+            return String[getRuntimeTypeIssuesSymbol](error, mode);
+        }
+        if ("outputError" in error) {
+            return runtimeOutput[getRuntimeTypeIssuesSymbol](error.outputError, mode);
+        }
+        return singleRuntimeTypeIssue("TemplateLiteral", error, formatTemplateLiteralError);
+    };
+    const canonicalStringFromUnknown = (value, options = firstValidationOptions) => {
+        const stringResult = String.fromUnknown(value, options);
+        return stringResult.ok
+            ? canonicalizeString(stringResult.value, options)
+            : stringResult;
+    };
+    const canonicalStringFrom = createFromOperation((value, options = firstValidationOptions) => canonicalizeString(value, options));
+    const stringType = createTypeNode("TemplateLiteral", String, canonicalStringFromUnknown, (value) => validateCanonicalString(value, firstValidationOptions).ok, validateCanonicalString, canonicalStringFrom, identity, getTypeIssues, reflection);
+    const fromUnknown = (value, options = firstValidationOptions) => {
+        const stringResult = String.fromUnknown(value, options);
+        if (!stringResult.ok)
+            return stringResult;
+        // The internal parser has one broad signature, but a statically frameless
+        // declaration cannot return its framing error.
+        return decodeString(stringResult.value, options);
+    };
+    const fromCanonicalString = (value, options = firstValidationOptions) => {
+        String.from(value);
+        const result = decodeString(value, options);
+        if (!result.ok || encodeCaptures(result.value) !== value) {
+            throw new Error("Expected TemplateLiteral.", {
+                cause: result.ok
+                    ? {
+                        type: "TemplateLiteral",
+                        value,
+                    }
+                    : result.error,
+            });
+        }
+        return result;
+    };
+    const fromString = (value, options = firstValidationOptions) => {
+        String.from(value);
+        return decodeString(value, options);
+    };
+    fromCanonicalString.parent = fromString;
+    const from = createFromOperation(fromCanonicalString);
+    const type = createTypeNode("TemplateLiteral", stringType, fromUnknown, runtimeOutput.is, runtimeOutput[outputValidationSymbol], from, encodeCaptures, getTypeIssues, reflection);
+    type.from.parent =
+        fromCanonicalString;
+    return type;
+};
+/**
+ * Template literal {@link Type} for validation.
+ *
+ * Creates a canonical string Type from fixed strings and string-encoded Types.
+ *
+ * Use this factory when Output should remain a string. Switch to
+ * {@link templateLiteralParser} when the individual Type parts should be
+ * decoded into a Tuple.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { templateLiteral, union } from "@evolu/common";
+ *
+ * const Language = union("en", "cs");
+ * const Region = union("US", "CZ");
+ * const Locale = templateLiteral(Language, "-", Region);
+ *
+ * expectTypeOf<typeof Locale.Output>().toEqualTypeOf<
+ *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ"
+ * >();
+ * expectOk(Locale.fromUnknown("cs-CZ"), "cs-CZ");
+ * expect(Locale.is("fr-CZ")).toBe(false);
+ * ```
+ *
+ * @group Template literals
+ */
+export const templateLiteral = (...parts) => createTemplateLiteralParserType(parts).parent;
+const formatTemplateLiteralError = (error) => `The value ${safelyStringifyUnknownValue(error.value)} does not match the template literal.`;
+const compileTemplateLiteralParser = (parts) => {
+    let framing = emptyTemplateLiteralFraming;
+    let fixedPartsWidth = 0;
+    const compiledParts = parts.map((part) => {
+        const partFraming = getTemplateLiteralPartFraming(part);
+        framing = concatenateTemplateLiteralFraming(framing, partFraming);
+        fixedPartsWidth += partFraming.width ?? 0;
+        return [part, partFraming.width];
+    });
+    return (input) => {
+        const inputCodePoints = globalThis.Array.from(input);
+        const variableWidth = inputCodePoints.length - fixedPartsWidth;
+        if (variableWidth < 0) {
+            return err({ type: "TemplateLiteral", value: input });
+        }
+        const captures = [];
+        let position = 0;
+        for (const [part, width] of compiledParts) {
+            const partWidth = width ?? variableWidth;
+            const value = inputCodePoints
+                .slice(position, position + partWidth)
+                .join("");
+            if (typeof part === "string") {
+                if (value !== part) {
+                    return err({ type: "TemplateLiteral", value: input });
+                }
+            }
+            else {
+                captures.push(value);
+            }
+            position += partWidth;
+        }
+        return position === inputCodePoints.length
+            ? ok(captures)
+            : err({ type: "TemplateLiteral", value: input });
+    };
+};
+const emptyTemplateLiteralFraming = {
+    width: 0,
+    canBeEmpty: true,
+    canStartWithLowSurrogate: false,
+    canEndWithHighSurrogate: false,
+};
+const unknownTemplateLiteralFraming = {
+    width: null,
+    canBeEmpty: true,
+    canStartWithLowSurrogate: true,
+    canEndWithHighSurrogate: true,
+};
+const concatenateTemplateLiteralFraming = (left, right) => {
+    assert(!(left.canEndWithHighSurrogate && right.canStartWithLowSurrogate), "A TemplateLiteral cannot form a Unicode surrogate pair across part boundaries.");
+    return {
+        width: left.width !== null && right.width !== null
+            ? left.width + right.width
+            : null,
+        canBeEmpty: left.canBeEmpty && right.canBeEmpty,
+        canStartWithLowSurrogate: left.canStartWithLowSurrogate ||
+            (left.canBeEmpty && right.canStartWithLowSurrogate),
+        canEndWithHighSurrogate: right.canEndWithHighSurrogate ||
+            (right.canBeEmpty && left.canEndWithHighSurrogate),
+    };
+};
+const getStringTemplateLiteralFraming = (value) => {
+    const firstCodeUnit = value.charCodeAt(0);
+    const lastCodeUnit = value.charCodeAt(value.length - 1);
+    return {
+        width: globalThis.Array.from(value).length,
+        canBeEmpty: value.length === 0,
+        canStartWithLowSurrogate: firstCodeUnit >= 0xdc00 && firstCodeUnit <= 0xdfff,
+        canEndWithHighSurrogate: lastCodeUnit >= 0xd800 && lastCodeUnit <= 0xdbff,
+    };
+};
+const getTemplateLiteralPartFraming = (part) => {
+    if (typeof part === "string")
+        return getStringTemplateLiteralFraming(part);
+    const type = part;
+    if (type[templateLiteralSyntaxSymbol] === true) {
+        if (type.name === "Literal") {
+            return getStringTemplateLiteralFraming(type.expected);
+        }
+        if (type.name === "Union") {
+            const memberFramings = type.members.map(getTemplateLiteralPartFraming);
+            const width = memberFramings[0].width;
+            return {
+                width: width !== null &&
+                    memberFramings.every((framing) => framing.width === width)
+                    ? width
+                    : null,
+                canBeEmpty: memberFramings.some((framing) => framing.canBeEmpty),
+                canStartWithLowSurrogate: memberFramings.some((framing) => framing.canStartWithLowSurrogate),
+                canEndWithHighSurrogate: memberFramings.some((framing) => framing.canEndWithHighSurrogate),
+            };
+        }
+        if (type.name === "TemplateLiteral") {
+            return type.parts.reduce((framing, part) => concatenateTemplateLiteralFraming(framing, getTemplateLiteralPartFraming(part)), emptyTemplateLiteralFraming);
+        }
+    }
+    if (type.parent === null)
+        return unknownTemplateLiteralFraming;
+    return getTemplateLiteralPartFraming(type.parent);
+};
 export function brand(name, parent, validate, formatError) {
     return createChildType(name, parent, validate
         ? (value) => flatMapResult(validate(value), () => ok(value))
@@ -837,7 +1263,7 @@ export const capitalized = (parent) => brand("Capitalized", parent, (value) => {
  */
 export const CapitalizedString = /*#__PURE__*/ capitalized(String);
 /**
- * Adds a {@link Brand} requiring a string without surrounding whitespace.
+ * String {@link Brand} without surrounding whitespace.
  *
  * @group String
  */
@@ -863,7 +1289,7 @@ export const TrimmedString = /*#__PURE__*/ trimmed(String);
  */
 export const trim = (value) => value.trim();
 /**
- * Adds a {@link Brand} requiring a value to have at least `min` items.
+ * Minimum-length {@link Brand} requiring a value to have at least `min` items.
  *
  * @group String
  * @group Collection
@@ -890,7 +1316,7 @@ export const minLength = (min) => (parent) => {
  */
 export const NonEmptyTrimmedString = /*#__PURE__*/ minLength(1)(TrimmedString);
 /**
- * Adds a {@link Brand} requiring a value to have at most `max` items.
+ * Maximum-length {@link Brand} requiring a value to have at most `max` items.
  *
  * @group String
  * @group Collection
@@ -914,7 +1340,7 @@ export const NonEmptyTrimmedString100 = /*#__PURE__*/ maxLength(100)(NonEmptyTri
  */
 export const NonEmptyTrimmedString1000 = /*#__PURE__*/ maxLength(1000)(NonEmptyTrimmedString);
 /**
- * Adds a {@link Brand} requiring a value to have exactly `exact` items.
+ * Exact-length {@link Brand} requiring a value to have exactly `exact` items.
  *
  * @group String
  * @group Collection
@@ -926,7 +1352,7 @@ export const length = (exact) => (parent) => {
         : err({ type: name, value, exact }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} does not have the required length of ${error.exact}.`);
 };
 /**
- * Creates a string {@link Brand} that must match a regular expression.
+ * String {@link Brand} constrained by a regular expression.
  *
  * ### Example
  *
@@ -1133,7 +1559,7 @@ export const createIdAsUuidv7 = (deps, ..._validation) => {
     return uint8ArrayToBase64Url(bytes);
 };
 /**
- * A table-specific {@link Id} Type.
+ * Table-specific {@link Id} Type.
  *
  * @group String
  */
@@ -1187,7 +1613,7 @@ export const Int64FromInt64String = /*#__PURE__*/ transform("Int64FromInt64Strin
     to: (value) => globalThis.String(value),
 });
 /**
- * Adds a {@link Brand} requiring a number greater than or equal to zero.
+ * Number {@link Brand} requiring a value greater than or equal to zero.
  *
  * @group Number
  */
@@ -1199,7 +1625,7 @@ export const nonNegative = (parent) => brand("NonNegative", parent, (value) => v
  */
 export const NonNegativeNumber = /*#__PURE__*/ nonNegative(Number);
 /**
- * Adds a {@link Brand} requiring a number greater than zero.
+ * Number {@link Brand} requiring a value greater than zero.
  *
  * @group Number
  */
@@ -1214,7 +1640,7 @@ export const positive = (parent) => brand("Positive", parent, (value) => value >
  */
 export const PositiveNumber = /*#__PURE__*/ positive(NonNegativeNumber);
 /**
- * Adds a {@link Brand} requiring a number less than or equal to zero.
+ * Number {@link Brand} requiring a value less than or equal to zero.
  *
  * @group Number
  */
@@ -1226,7 +1652,7 @@ export const nonPositive = (parent) => brand("NonPositive", parent, (value) => v
  */
 export const NonPositiveNumber = /*#__PURE__*/ nonPositive(Number);
 /**
- * Adds a {@link Brand} requiring a number less than zero.
+ * Number {@link Brand} requiring a value less than zero.
  *
  * @group Number
  */
@@ -1241,7 +1667,7 @@ export const negative = (parent) => brand("Negative", parent, (value) => value <
  */
 export const NegativeNumber = /*#__PURE__*/ negative(NonPositiveNumber);
 /**
- * Adds a {@link Brand} requiring a number other than `NaN`.
+ * Number {@link Brand} requiring a value other than `NaN`.
  *
  * @group Number
  */
@@ -1260,7 +1686,7 @@ export const nonNaN = (parent) => brand("NonNaN", parent, (value) => globalThis.
  */
 export const NonNaNNumber = /*#__PURE__*/ nonNaN(Number);
 /**
- * Adds a {@link Brand} requiring a finite number.
+ * Number {@link Brand} requiring a finite value.
  *
  * @group Number
  */
@@ -1279,6 +1705,12 @@ export const FiniteNumber = /*#__PURE__*/ finite(NonNaNNumber);
  * @group Number
  */
 export const NonNegativeFiniteNumber = /*#__PURE__*/ nonNegative(FiniteNumber);
+/**
+ * Positive {@link FiniteNumber}.
+ *
+ * @group Number
+ */
+export const PositiveFiniteNumber = /*#__PURE__*/ positive(NonNegativeFiniteNumber);
 /**
  * Safe integer {@link Brand}.
  *
@@ -1360,7 +1792,7 @@ export const NonPositiveInt = /*#__PURE__*/ nonPositive(Int);
  */
 export const NegativeInt = /*#__PURE__*/ negative(NonPositiveInt);
 /**
- * Adds a {@link Brand} requiring a number greater than `min`.
+ * Number {@link Brand} requiring a value greater than `min`.
  *
  * @group Number
  */
@@ -1371,7 +1803,7 @@ export const greaterThan = (min) => (parent) => {
         : err({ type: name, value, min }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be greater than ${error.min}.`);
 };
 /**
- * Adds a {@link Brand} requiring a number greater than or equal to `min`.
+ * Number {@link Brand} requiring a value greater than or equal to `min`.
  *
  * @group Number
  */
@@ -1386,7 +1818,7 @@ export const greaterThanOrEqualTo = (min) => (parent) => {
         }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be greater than or equal to ${error.min}.`);
 };
 /**
- * Adds a {@link Brand} requiring a number less than `max`.
+ * Number {@link Brand} requiring a value less than `max`.
  *
  * @group Number
  */
@@ -1404,7 +1836,7 @@ export const lessThan = (max) => (parent) => {
 export const Age = /*#__PURE__*/ brand("Age", 
 /*#__PURE__*/ lessThan(200)(NonNegativeInt));
 /**
- * Adds a {@link Brand} requiring a number less than or equal to `max`.
+ * Number {@link Brand} requiring a value less than or equal to `max`.
  *
  * @group Number
  */
@@ -1424,51 +1856,147 @@ export const lessThanOrEqualTo = (max) => (parent) => {
 export const Ratio = /*#__PURE__*/ brand("Ratio", 
 /*#__PURE__*/ lessThanOrEqualTo(1)(NonNegativeFiniteNumber));
 /**
- * Canonical string representation of a positive base-10 decimal.
+ * Canonical string representation of a signed base-10 decimal value.
+ *
+ * Use this Type when a decimal value must remain exact instead of being
+ * converted to an IEEE-754 number. Equivalent values have one accepted
+ * representation, so leading zeroes, trailing fractional zeroes, `-0`, plus
+ * signs, and exponent notation are rejected.
+ *
+ * The decoded value remains a string. Arithmetic requires an explicit decimal
+ * or fixed-point representation.
  *
- * Each value has one spelling: leading zeroes, trailing fractional zeroes,
- * signs, and exponent notation are rejected. This preserves exact decimal
- * meaning without representing the value as an IEEE-754 number.
+ * TypeScript template literal types can describe a fixed number of digit
+ * positions, but not the arbitrarily long integer and fractional parts accepted
+ * here. `DecimalString` therefore uses a {@link Brand} so its TypeScript type
+ * does not accept strings that have not been validated.
+ *
+ * Use these predefined Types or their corresponding factories to add sign
+ * constraints to compatible decimal string Types:
+ *
+ * - {@link NonNegativeDecimalString} / {@link nonNegativeDecimalString}
+ * - {@link PositiveDecimalString} / {@link positiveDecimalString}
+ * - {@link NonPositiveDecimalString} / {@link nonPositiveDecimalString}
+ * - {@link NegativeDecimalString} / {@link negativeDecimalString}
  *
  * ### Example
  *
  * ```ts
- * import { PositiveDecimalString } from "@evolu/common";
+ * import { DecimalString } from "@evolu/common";
  *
- * expectOk(PositiveDecimalString.fromUnknown("0.3"), "0.3");
- * expectOk(PositiveDecimalString.fromUnknown("25"), "25");
+ * expectOk(DecimalString.fromUnknown("-10.25"), "-10.25");
+ * expectOk(DecimalString.fromUnknown("0"), "0");
+ * expectOk(DecimalString.fromUnknown("10.25"), "10.25");
  *
- * expectErr(PositiveDecimalString.fromUnknown("0.30"), {
- *   type: "PositiveDecimalString",
- *   value: "0.30",
+ * expectErr(DecimalString.fromUnknown("10.250"), {
+ *   type: "DecimalString",
+ *   value: "10.250",
  * });
  * ```
  *
  * @group Number
  */
-export const PositiveDecimalString = /*#__PURE__*/ brand("PositiveDecimalString", String, (value) => /^(?:[1-9]\d*|(?:0|[1-9]\d*)\.\d*[1-9])$/.test(value)
+export const DecimalString = /*#__PURE__*/ brand("DecimalString", String, (value) => /^(?:0|-?(?:[1-9]\d*|(?:0|[1-9]\d*)\.\d*[1-9]))$/.test(value)
+    ? ok()
+    : err({ type: "DecimalString", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a canonical decimal string.`);
+/**
+ * {@link DecimalString} Brand requiring a value greater than or equal to zero.
+ *
+ * @group Number
+ */
+export const nonNegativeDecimalString = (parent) => brand("NonNegativeDecimalString", parent, (value) => value[0] !== "-"
+    ? ok()
+    : err({
+        type: "NonNegativeDecimalString",
+        value,
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a non-negative decimal string.`);
+/**
+ * Non-negative {@link DecimalString}.
+ *
+ * @group Number
+ */
+export const NonNegativeDecimalString = 
+/*#__PURE__*/ nonNegativeDecimalString(DecimalString);
+/**
+ * {@link DecimalString} Brand requiring a value greater than zero.
+ *
+ * @group Number
+ */
+export const positiveDecimalString = (parent) => brand("PositiveDecimalString", parent, (value) => value !== "0" && value[0] !== "-"
     ? ok()
     : err({
         type: "PositiveDecimalString",
         value,
-    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a canonical positive decimal string.`);
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a positive decimal string.`);
 /**
- * Adds a {@link Brand} requiring a number to be a multiple of an exact decimal
- * `divisor`.
+ * Positive {@link DecimalString}.
  *
- * The literal divisor is validated against {@link PositiveDecimalString} and
- * encoded in the resulting Brand name. A runtime string cannot define this Type
- * because its exact value is not available to TypeScript for that name.
- * Validation does not round: `"0.1"` accepts `0.3`, but rejects `0.1 + 0.2`
- * because that expression evaluates to `0.30000000000000004`.
+ * Also satisfies {@link NonNegativeDecimalString}, so it can be used wherever a
+ * non-negative decimal string is required.
+ *
+ * @group Number
+ */
+export const PositiveDecimalString = /*#__PURE__*/ positiveDecimalString(NonNegativeDecimalString);
+/**
+ * {@link DecimalString} Brand requiring a value less than or equal to zero.
+ *
+ * @group Number
+ */
+export const nonPositiveDecimalString = (parent) => brand("NonPositiveDecimalString", parent, (value) => value === "0" || value[0] === "-"
+    ? ok()
+    : err({
+        type: "NonPositiveDecimalString",
+        value,
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a non-positive decimal string.`);
+/**
+ * Non-positive {@link DecimalString}.
+ *
+ * @group Number
+ */
+export const NonPositiveDecimalString = 
+/*#__PURE__*/ nonPositiveDecimalString(DecimalString);
+/**
+ * {@link DecimalString} Brand requiring a value less than zero.
+ *
+ * @group Number
+ */
+export const negativeDecimalString = (parent) => brand("NegativeDecimalString", parent, (value) => value[0] === "-"
+    ? ok()
+    : err({
+        type: "NegativeDecimalString",
+        value,
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a negative decimal string.`);
+/**
+ * Negative {@link DecimalString}.
+ *
+ * Also satisfies {@link NonPositiveDecimalString}, so it can be used wherever a
+ * non-positive decimal string is required.
+ *
+ * @group Number
+ */
+export const NegativeDecimalString = /*#__PURE__*/ negativeDecimalString(NonPositiveDecimalString);
+/**
+ * Number {@link Brand} requiring an exact decimal multiple of `divisor`.
+ *
+ * The divisor must be one canonical positive decimal string literal because its
+ * exact value is encoded in the resulting Brand name. The declaration is
+ * validated at compile time and is never converted to an IEEE-754 number.
+ *
+ * Validation treats each finite Number as its canonical decimal representation
+ * and checks exact base-10 divisibility. It does not use floating-point
+ * remainder, apply a tolerance, or round to the divisor's precision.
  *
  * ### Example
  *
  * ```ts
- * import { FiniteNumber, multipleOf } from "@evolu/common";
+ * import { FiniteNumber, multipleOf, type Brand } from "@evolu/common";
  *
  * const Tenths = multipleOf("0.1")(FiniteNumber);
  *
+ * expectTypeOf<typeof Tenths.Output>().toEqualTypeOf<
+ *   FiniteNumber & Brand<"MultipleOf0.1">
+ * >();
+ *
  * expectOk(Tenths.fromUnknown(0.3), 0.3);
  * expectErr(Tenths.fromUnknown(0.31), {
  *   type: "MultipleOf0.1",
@@ -1480,31 +2008,18 @@ export const PositiveDecimalString = /*#__PURE__*/ brand("PositiveDecimalString"
  * @group Number
  */
 export const multipleOf = (divisor) => {
-    // TODO: Define the positive-decimal literal domain with templateLiteral so
-    // its TypeScript type is inferred from runtime Type code, then require that
-    // literal Type here instead of accepting a string guarded by assertType.
-    assertType(PositiveDecimalString, divisor);
     const name = `MultipleOf${divisor}`;
     const decimalDivisor = decimalStringToParts(divisor);
     return (parent) => brand(name, parent, (value) => {
         let isMultiple = false;
         if (globalThis.Number.isFinite(value)) {
             const decimalValue = decimalStringToParts(value.toString());
-            const exponentDifference = decimalValue.exponent - decimalDivisor.exponent;
-            if (exponentDifference >= 0) {
-                isMultiple =
-                    (decimalValue.coefficient *
-                        10n ** globalThis.BigInt(exponentDifference)) %
-                        decimalDivisor.coefficient ===
-                        0n;
-            }
-            else {
-                isMultiple =
-                    decimalValue.coefficient %
-                        (decimalDivisor.coefficient *
-                            10n ** globalThis.BigInt(-exponentDifference)) ===
-                        0n;
-            }
+            const exponent = Math.min(decimalValue.exponent, decimalDivisor.exponent);
+            const valueCoefficient = decimalValue.coefficient *
+                10n ** globalThis.BigInt(decimalValue.exponent - exponent);
+            const divisorCoefficient = decimalDivisor.coefficient *
+                10n ** globalThis.BigInt(decimalDivisor.exponent - exponent);
+            isMultiple = valueCoefficient % divisorCoefficient === 0n;
         }
         return isMultiple
             ? ok()
@@ -1534,7 +2049,7 @@ const decimalStringToParts = (value) => {
     return { coefficient, exponent };
 };
 /**
- * Adds a {@link Brand} requiring a number to be within an inclusive range.
+ * Number {@link Brand} requiring a value within an inclusive range.
  *
  * @group Number
  */
@@ -1966,6 +2481,57 @@ const createTupleType = (typeElements) => {
     return createTypeNode("Tuple", parent, fromUnknown, is, validateOutput, from, to, getTypeIssues, { elements: typeElements });
 };
 const validateTupleItems = (value, elements, validate, options, checkStructure) => validateIndexedArrayItems("Tuple", value, (value, elementOptions, index) => validate(elements[index], value, elementOptions, index), options, checkStructure);
+/**
+ * Decimal digit from `"0"` to `"9"`.
+ *
+ * @group String
+ */
+export const Digit = /*#__PURE__*/ union("0", "1", "2", "3", "4", "5", "6", "7", "8", "9");
+/**
+ * Decimal digit from `"1"` to `"9"`.
+ *
+ * @group String
+ */
+export const Digit1To9 = /*#__PURE__*/ union("1", "2", "3", "4", "5", "6", "7", "8", "9");
+/**
+ * Decimal string from `"1"` to `"6"`.
+ *
+ * @group String
+ */
+export const Digit1To6 = /*#__PURE__*/ union("1", "2", "3", "4", "5", "6");
+/**
+ * Decimal string from `"1"` to `"23"`.
+ *
+ * @group String
+ */
+export const Digit1To23 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral("1", Digit), 
+/*#__PURE__*/ templateLiteral("2", 
+/*#__PURE__*/ union("0", "1", "2", "3")));
+/**
+ * Decimal string from `"1"` to `"51"`.
+ *
+ * @group String
+ */
+export const Digit1To51 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral(
+/*#__PURE__*/ union("1", "2", "3", "4"), Digit), 
+/*#__PURE__*/ templateLiteral("5", /*#__PURE__*/ union("0", "1")));
+/**
+ * Decimal string from `"1"` to `"99"`.
+ *
+ * @group String
+ */
+export const Digit1To99 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit));
+/**
+ * Decimal string from `"1"` to `"59"`.
+ *
+ * @group String
+ */
+export const Digit1To59 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral(
+/*#__PURE__*/ union("1", "2", "3", "4", "5"), Digit));
 const createObjectRuntimeTypeIssues = (defaultFormatter, props, recordType) => (error, mode) => {
     const objectError = error;
     if (objectError.reason.kind !== "Properties") {
@@ -2738,7 +3304,7 @@ const createRecordPropertyError = (issue) => ({
     reason: { kind: "Entries", issues: [issue] },
 });
 /**
- * Creates an {@link object} Type with every property optional.
+ * Object {@link Type} with every property optional.
  *
  * No property is required, but every present property must still satisfy its
  * Type.
@@ -2769,7 +3335,8 @@ export const partial = (props, ..._validation) => {
     return createObjectType(partialProps);
 };
 /**
- * Makes every property whose Union Type includes {@link Null} optional.
+ * Object {@link Type} making every property whose Union Type includes
+ * {@link Null} optional.
  *
  * The property retains its original Union Type, so consumers may omit it, set
  * it to `null`, or provide any other member of that Union. Properties without
@@ -2814,7 +3381,7 @@ export const nullableToOptional = (props, ..._validation) => {
     return createObjectType(optionalProps);
 };
 /**
- * Creates an {@link object} Type without the selected declared properties.
+ * Object {@link Type} without the selected declared properties.
  *
  * @group Objects
  */
@@ -3425,7 +3992,7 @@ export const JsonValueFromJson = /*#__PURE__*/ transform("JsonValueFromJson", Js
     to: stringifyJsonValue,
 });
 /**
- * Creates a branded {@link Json} Type and total conversions for another Type.
+ * Branded {@link Json} Type and total conversions for another Type.
  *
  * Use this factory when a domain value must be stored as JSON text while its
  * exact Type remains visible to TypeScript, such as a JSON column in an Evolu