@asterdoc/format 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Paradoc AI, Inc.
+
+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.
+
+---
+
+**Trademark Notice**: This license does not grant permission to use the trade names, trademarks, service marks, logos, taglines, or product names of Asterdoc, except as required for reasonable and customary use in describing the origin of the Software.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://asterdoc.com?utm_source=github&utm_medium=format" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.asterdoc.com/asterdoc-logo-400x400-dark.png" type="image/png">
+      <img src="https://assets.asterdoc.com/asterdoc-logo-400x400-dark.png" height="64" alt="Asterdoc logo">
+    </picture>
+  </a>
+  <br />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">@asterdoc/format</h1>
+
+<div align="center">
+
+[![Asterdoc documentation](https://img.shields.io/badge/Documentation-Asterdoc-red.svg)](https://docs.asterdoc.com?utm_source=github&utm_medium=format)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/asterdoc?style=social)](https://x.com/asterdoc)
+
+</div>
+
+`@asterdoc/format` presents structured Asterdoc values as human-readable text. It keeps display policy separate from stored values, localized input parsing, currency conversion, and artifact validation.
+
+The formatter presents numbers, money, percentage points, people, organizations, parties, phones, postal addresses, coordinates, bounding boxes, identifications, attachments, signatures, dates, datetimes, times, ISO 8601 durations, and the selection values a form field carries: booleans, single choices, multiple choices, and ratings. It is immutable and reusable, so repeated calls under one effective policy reuse bounded Intl formatter caches.
+
+```ts
+import { createFormatter } from '@asterdoc/format'
+
+const formatter = createFormatter({ locale: 'de-DE' })
+
+formatter.formatNumber(1234567.89) // '1.234.567,89'
+formatter.formatMoney({ amount: 1500.5, currency: 'USD' }) // '1.500,50 $'
+formatter.formatPercentage(8.25) // '8,25 %'
+```
+
+Contact and capture values use the same standalone and dynamic operations. This block uses an `en-US` formatter:
+
+```ts
+const us = createFormatter({ locale: 'en-US' })
+
+us.formatPerson({ firstName: 'Jane', lastName: 'Smith' }) // 'Jane Smith'
+us.formatPhone({ number: '+442071838750', extension: '42' }) // '+442071838750 ext. 42'
+us.formatAddress({
+  line1: '10 Downing Street',
+  locality: 'London',
+  region: 'Greater London',
+  postalCode: 'SW1A 2AA',
+  country: 'GB',
+}) // '10 Downing Street, London, Greater London, SW1A 2AA, GB'
+
+us.formatCoordinate({ lat: 40.7128, lon: -74.006 }) // '40.7128; -74.006'
+us.formatBbox({
+  southWest: { lat: 40.4774, lon: -74.2591 },
+  northEast: { lat: 40.9176, lon: -73.7004 },
+}) // '40.4774; -74.2591 | 40.9176; -73.7004'
+us.formatIdentification({
+  type: 'passport',
+  number: 'A1',
+  issueDate: '2020-01-15',
+}) // 'passport: A1 (issued Jan 15, 2020)'
+us.formatAttachment({ name: 'contract.pdf', mimeType: 'application/pdf' }) // 'contract.pdf (application/pdf)'
+us.formatSignature({ timestamp: '2026-09-04T15:30:00Z', method: 'drawn' }) // 'Signature (drawn) on Sep 4, 2026'
+```
+
+Coordinates use `latitude; longitude`; bounding boxes use `southWest | northEast`. The semicolon and pipe separators remain unambiguous when a locale uses a comma as its decimal separator. Coordinate values default to up to nine fractional digits and accept the same number precision options as `formatNumber`.
+
+Address country and document locale are independent. The default `layout: 'country'` policy provides layouts for US, GB, DE, FR, and SA and returns an `unsupported` result for another country. Select `layout: 'generic'` when a component-preserving layout is appropriate, or provide a `countryLayouts` object whose ISO country-code keys map to formatter functions for another country. Party values with only the shared `name` member are ambiguous; use `partyType: 'person'` or provide a distinguishing person or organization member.
+
+Money always supplies its currency. A bare amount is never assigned a default currency. Percentage values use Asterdoc's percentage-point scale, so `8.25` means `8.25%`, not `825%`.
+
+Temporal values keep their declared meaning. A plain `YYYY-MM-DD` date is a calendar date and is never shifted by timezone. A `Date` object and a datetime string with `Z` or a numeric offset are instants and use the configured `timeZone`; an offsetless datetime string is a local calendar/clock value and stays unchanged. Times of day are formatted as clock values in UTC so the host timezone never changes them. All temporal formatters default to Gregorian calendar, UTC for instants, and the selected locale's numbering system. Per-call options can choose a supported `calendar`, `numberingSystem`, `timeZone`, or Intl precision option.
+
+Durations use Asterdoc's canonical ISO 8601 syntax (`P[n]Y[n]M[n]W[n]DT[n]H[n]M[n]S`, with fractional seconds allowed). Zero components are omitted and a zero duration is shown as zero seconds. Duration components display with up to nine fractional digits by default; set `maximumFractionDigits` or related Intl number options to choose a different display precision without changing the stored duration. Duration unit labels are supplied for the initial English, German, French, and Arabic resources, and multiple components use the runtime's standard unit-list conventions. Additional locales must provide `duration.<unit>.<plural-category>` messages, such as `duration.day.one: '{value} day'`, or explicitly choose a configured `fallbackLocale` for package messages. The requested locale still controls number and list formatting when a message fallback is used. Without a supplied fallback language, missing package messages return `unsupported`.
+
+Selection values are presented with what the field declares. A boolean prints the locale's own yes and no words, which `trueLabel` and `falseLabel` replace. An enum and a multiselect print the label of the option that carries the value; a value no option declares is `invalid`, unless `unknownOption: 'value'` explicitly prints it as itself. A multiselect joins those labels with the locale's own list conjunction and separator, in the locale's direction; `listType` (`conjunction`, `disjunction`, `unit`) and `listStyle` (`long`, `short`, `narrow`) choose the relation and its verbosity. A rating prints with the scale it was given on.
+
+```ts
+const services = [{ value: 'plumbing', label: 'Plumbing' }, { value: 'wiring', label: 'Wiring' }]
+
+formatter.formatBoolean(true) // 'Ja' for de-DE
+formatter.formatEnum('wiring', { options: services }) // 'Wiring'
+formatter.formatMultiselect(['plumbing', 'wiring'], { options: services }) // 'Plumbing und Wiring' for de-DE
+formatter.formatRating(4, { max: 5 }) // '4 von 5' for de-DE
+```
+
+Two selection presentations can be unavailable rather than wrong, and both return an `unsupported` result the caller decides about. A rating with no `max` has no scale to print; a runtime whose locale data carries no list conjunction cannot join a multiselect. Asterdoc's renderers fall back to the plain number and to a comma join respectively, and keep the formatter's outcome on the value. The fallback join uses a plain comma on purpose: it only runs when the runtime holds no list data for the locale, so there is no locale-correct separator left to use.
+
+Strict methods return text and throw a `FormatError` for missing, incomplete, invalid, unsupported, or unexpected values. Use the safe methods when a progressive flow needs structured diagnostics:
+
+```ts
+const result = formatter.safeFormatMoney({ amount: 10 })
+// { success: false, status: 'incomplete', issues: [...] }
+```
+
+The safe methods are named `safeFormatMoney`, `safeFormatNumber`, `safeFormatPercentage`, `safeFormatAddress`, `safeFormatPhone`, `safeFormatPerson`, `safeFormatOrganization`, `safeFormatParty`, `safeFormatCoordinate`, `safeFormatBbox`, `safeFormatIdentification`, `safeFormatAttachment`, `safeFormatSignature`, `safeFormatDate`, `safeFormatDatetime`, `safeFormatTime`, `safeFormatDuration`, `safeFormatBoolean`, `safeFormatEnum`, `safeFormatMultiselect`, and `safeFormatRating`. Dynamic callers can use `formatValue(kind, value)` or `safeFormatValue(kind, value)`. A kind the formatter does not know returns `unsupported` with the code `unknown_kind`.
+
+A bad option is `invalid` with the code `invalid_options`, like a bad value: a malformed locale, an unknown timezone, calendar, or numbering system, or an Intl option out of range. `unsupported` means the input is right and the runtime or the resources fall short: a locale the runtime has no data for (`unsupported_locale`), a missing package message (`missing_message`), or a country with no address layout (`unsupported_country_layout`).
+
+A value family that formats through another kind, such as a signature's date, a bounding box's corners, a rating's number, or a multiselect's labels, passes only its own options. The other kind's formatter-level options do not apply, so `number: { maximumFractionDigits: 0 }` does not round a rating. Overrides of the other kind still apply.
+
+Locale, numbering-system, calendar, and timezone choices are independent. The default locale is `en-US`, the default timezone `UTC`, and the default calendar Gregorian. An unsupported runtime locale fails at construction unless `unsupportedLocale: 'fallback'` and an explicit `fallbackLocale` are provided. `fallbackLocale` also supplies package-authored messages, for every value family, when the requested runtime locale is supported but has no matching messages; it does not change the requested locale used for Intl numbers, dates, times, or lists.
+
+```ts
+const amountOnly = formatter.compose({
+  money: { currencyDisplay: 'none' },
+})
+
+amountOnly.formatMoney({ amount: 1500.5, currency: 'USD' }) // '1.500,50'
+```
+
+`currencyDisplay: 'none'` drops the symbol and keeps the currency's fraction digits (two for USD, none for JPY) unless you set digits.
+
+`compose` and `withOverrides` return independent formatter instances. Overrides can delegate to the previous implementation through the third callback argument, without recursively invoking themselves.
+
+`cacheStats()` reports the size, hits, misses, and limit of each bounded cache: `number`, `money`, `percentage`, `date`, `datetime`, `time`, `timeZone`, `duration`, `durationPlural`, `durationList`, and `selectionList`. `cacheSize` (default 64, from 1 to 256) bounds each one; the least recently used entry is dropped first.

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { FormatKind, FormatterOptions, Formatter, FormatInputByKind, FormatCallOptions, FormatResult, FormatStatus, FormatIssue } from '@asterdoc/types';
+export { AddressFormatOptions, AddressLayoutContext, AddressLayoutFormatter, AddressLayoutPolicy, AttachmentFormatOptions, BboxFormatOptions, BooleanFormatOptions, CaptureFormatImplementation, CaptureFormatImplementationContext, CaptureFormatKind, CaptureValueByKind, ContactFormatImplementation, ContactFormatImplementationContext, ContactFormatKind, ContactValueByKind, CoordinateFormatOptions, DateFormatOptions, DatetimeFormatOptions, DurationFormatOptions, EnumFormatOptions, EnumOption, EnumOptionValue, FormatCallOptions, FormatImplementation, FormatImplementationContext, FormatInputByKind, FormatIssue, FormatKind, FormatOptionsByKind, FormatResult, FormatStatus, FormattedResult, Formatter, FormatterCacheBucket, FormatterCacheBucketStats, FormatterCacheStats, FormatterMessages, FormatterOptions, FormatterOverrides, FormatterProgressivePolicy, IdentificationFormatOptions, MoneyFormatOptions, MultiselectFormatOptions, NumberFormatOptions, NumericFormatKind, NumericValueByKind, OrganizationFormatOptions, PartyFormatOptions, PercentageFormatOptions, PersonFormatOptions, PhoneFormatOptions, RatingDisplay, RatingFormatOptions, SelectionFormatImplementation, SelectionFormatImplementationContext, SelectionFormatKind, SelectionListStyle, SelectionListType, SelectionValueByKind, SignatureFormatOptions, TemporalFormatImplementation, TemporalFormatImplementationContext, TemporalFormatKind, TemporalFormatOptions, TemporalValueByKind, TimeFormatOptions, UnformattedResult, UnknownOptionPolicy, UnsupportedLocalePolicy } from '@asterdoc/types';
+
+/** Value families understood by the public formatter contract. */
+declare const FORMAT_KINDS: readonly FormatKind[];
+
+declare function createFormatter(options?: FormatterOptions): Formatter;
+declare const defaultFormatter: Formatter;
+declare function formatNumber(value: FormatInputByKind['number'], options?: FormatCallOptions<'number'>): string;
+declare function formatAddress(value: FormatInputByKind['address'], options?: FormatCallOptions<'address'>): string;
+declare function formatMoney(value: FormatInputByKind['money'], options?: FormatCallOptions<'money'>): string;
+declare function formatPercentage(value: FormatInputByKind['percentage'], options?: FormatCallOptions<'percentage'>): string;
+declare function formatPhone(value: FormatInputByKind['phone'], options?: FormatCallOptions<'phone'>): string;
+declare function formatPerson(value: FormatInputByKind['person'], options?: FormatCallOptions<'person'>): string;
+declare function formatOrganization(value: FormatInputByKind['organization'], options?: FormatCallOptions<'organization'>): string;
+declare function formatParty(value: FormatInputByKind['party'], options?: FormatCallOptions<'party'>): string;
+declare function formatDate(value: FormatInputByKind['date'], options?: FormatCallOptions<'date'>): string;
+declare function formatDatetime(value: FormatInputByKind['datetime'], options?: FormatCallOptions<'datetime'>): string;
+declare function formatTime(value: FormatInputByKind['time'], options?: FormatCallOptions<'time'>): string;
+declare function formatDuration(value: FormatInputByKind['duration'], options?: FormatCallOptions<'duration'>): string;
+declare function formatCoordinate(value: FormatInputByKind['coordinate'], options?: FormatCallOptions<'coordinate'>): string;
+declare function formatBbox(value: FormatInputByKind['bbox'], options?: FormatCallOptions<'bbox'>): string;
+declare function formatIdentification(value: FormatInputByKind['identification'], options?: FormatCallOptions<'identification'>): string;
+declare function formatAttachment(value: FormatInputByKind['attachment'], options?: FormatCallOptions<'attachment'>): string;
+declare function formatSignature(value: FormatInputByKind['signature'], options?: FormatCallOptions<'signature'>): string;
+declare function formatBoolean(value: FormatInputByKind['boolean'], options?: FormatCallOptions<'boolean'>): string;
+declare function formatEnum(value: FormatInputByKind['enum'], options?: FormatCallOptions<'enum'>): string;
+declare function formatMultiselect(value: FormatInputByKind['multiselect'], options?: FormatCallOptions<'multiselect'>): string;
+declare function formatRating(value: FormatInputByKind['rating'], options?: FormatCallOptions<'rating'>): string;
+declare function formatValue<K extends FormatKind>(kind: K, value: FormatInputByKind[K], options?: FormatCallOptions<K>): string;
+declare function safeFormatValue<K extends FormatKind>(kind: K, value: FormatInputByKind[K], options?: FormatCallOptions<K>): FormatResult;
+declare function safeFormatNumber(value: FormatInputByKind['number'], options?: FormatCallOptions<'number'>): FormatResult;
+declare function safeFormatAddress(value: FormatInputByKind['address'], options?: FormatCallOptions<'address'>): FormatResult;
+declare function safeFormatMoney(value: FormatInputByKind['money'], options?: FormatCallOptions<'money'>): FormatResult;
+declare function safeFormatPercentage(value: FormatInputByKind['percentage'], options?: FormatCallOptions<'percentage'>): FormatResult;
+declare function safeFormatPhone(value: FormatInputByKind['phone'], options?: FormatCallOptions<'phone'>): FormatResult;
+declare function safeFormatPerson(value: FormatInputByKind['person'], options?: FormatCallOptions<'person'>): FormatResult;
+declare function safeFormatOrganization(value: FormatInputByKind['organization'], options?: FormatCallOptions<'organization'>): FormatResult;
+declare function safeFormatParty(value: FormatInputByKind['party'], options?: FormatCallOptions<'party'>): FormatResult;
+declare function safeFormatDate(value: FormatInputByKind['date'], options?: FormatCallOptions<'date'>): FormatResult;
+declare function safeFormatDatetime(value: FormatInputByKind['datetime'], options?: FormatCallOptions<'datetime'>): FormatResult;
+declare function safeFormatTime(value: FormatInputByKind['time'], options?: FormatCallOptions<'time'>): FormatResult;
+declare function safeFormatDuration(value: FormatInputByKind['duration'], options?: FormatCallOptions<'duration'>): FormatResult;
+declare function safeFormatCoordinate(value: FormatInputByKind['coordinate'], options?: FormatCallOptions<'coordinate'>): FormatResult;
+declare function safeFormatBbox(value: FormatInputByKind['bbox'], options?: FormatCallOptions<'bbox'>): FormatResult;
+declare function safeFormatIdentification(value: FormatInputByKind['identification'], options?: FormatCallOptions<'identification'>): FormatResult;
+declare function safeFormatAttachment(value: FormatInputByKind['attachment'], options?: FormatCallOptions<'attachment'>): FormatResult;
+declare function safeFormatSignature(value: FormatInputByKind['signature'], options?: FormatCallOptions<'signature'>): FormatResult;
+declare function safeFormatBoolean(value: FormatInputByKind['boolean'], options?: FormatCallOptions<'boolean'>): FormatResult;
+declare function safeFormatEnum(value: FormatInputByKind['enum'], options?: FormatCallOptions<'enum'>): FormatResult;
+declare function safeFormatMultiselect(value: FormatInputByKind['multiselect'], options?: FormatCallOptions<'multiselect'>): FormatResult;
+declare function safeFormatRating(value: FormatInputByKind['rating'], options?: FormatCallOptions<'rating'>): FormatResult;
+
+/** A structured failure raised by a strict formatter operation. */
+declare class FormatError extends Error {
+    readonly status: Exclude<FormatStatus, 'formatted'>;
+    readonly kind: FormatKind | string;
+    readonly issues: readonly FormatIssue[];
+    constructor(status: Exclude<FormatStatus, 'formatted'>, kind: FormatKind | string, issues: readonly FormatIssue[]);
+}
+/**
+ * A formatter or call option is not usable. Construction throws it; a safe
+ * call reports it as `invalid` / `invalid_options`.
+ */
+declare class FormatConfigurationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A well-formed locale this runtime has no data for. Construction throws it; a
+ * safe call reports it as `unsupported` / `unsupported_locale`, because the
+ * option is right and the runtime is what falls short.
+ */
+declare class UnsupportedLocaleError extends FormatConfigurationError {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare function isFormatError(value: unknown): value is FormatError;
+
+/**
+ * The `unsupported` outcome a rating with no declared scale returns. A caller
+ * that has a documented plain presentation keys its fallback off this code.
+ */
+declare const MISSING_RATING_SCALE = "missing_scale";
+/**
+ * The `unsupported` outcome a multiselect returns when the runtime carries no
+ * list conjunction for the locale. A caller that has a documented plain join
+ * keys its fallback off this code.
+ */
+declare const UNSUPPORTED_LIST_JOIN = "unsupported_list";
+
+export { FORMAT_KINDS, FormatConfigurationError, FormatError, MISSING_RATING_SCALE, UNSUPPORTED_LIST_JOIN, UnsupportedLocaleError, createFormatter, defaultFormatter, formatAddress, formatAttachment, formatBbox, formatBoolean, formatCoordinate, formatDate, formatDatetime, formatDuration, formatEnum, formatIdentification, formatMoney, formatMultiselect, formatNumber, formatOrganization, formatParty, formatPercentage, formatPerson, formatPhone, formatRating, formatSignature, formatTime, formatValue, isFormatError, safeFormatAddress, safeFormatAttachment, safeFormatBbox, safeFormatBoolean, safeFormatCoordinate, safeFormatDate, safeFormatDatetime, safeFormatDuration, safeFormatEnum, safeFormatIdentification, safeFormatMoney, safeFormatMultiselect, safeFormatNumber, safeFormatOrganization, safeFormatParty, safeFormatPercentage, safeFormatPerson, safeFormatPhone, safeFormatRating, safeFormatSignature, safeFormatTime, safeFormatValue };