@noy-db/hub 0.2.0-pre.17 → 0.2.0-pre.19

package/dist/{strategy-CLC1j79g.d.cts → strategy-C5ol6NdV.d.cts}

@@ -1,4 +1,4 @@
-import { N as NoydbError } from './errors-Dz64FA65.cjs';
+import { N as NoydbError } from './errors-DL-zTrrF.cjs';
 
 /**
  * Aggregation reducers for the query DSL.
@@ -432,6 +432,305 @@ declare function money(options: MoneyOptions): MoneyDescriptor;
 /** Runtime predicate for detecting a {@link MoneyDescriptor}. */
 declare function isMoneyDescriptor(x: unknown): x is MoneyDescriptor;
 
+/**
+ * Per-layer i18n resolution policy.
+ *
+ * `onMissing` governs what happens when a multilingual field is resolved
+ * to a target locale that is absent. It may be a single scalar policy or
+ * a per-layer map, so a field can be lenient at the app read boundary but
+ * strict inside a materialized view.
+ *
+ * Effective policy for layer `λ`:
+ *
+ * ```
+ * explicit(λ) = typeof onMissing === 'object' ? onMissing[λ] : undefined
+ * scalar      = typeof onMissing === 'string' ? onMissing : undefined
+ * policy(λ)   = explicit(λ) ?? layerDefault(λ) ?? scalar ?? 'throw'
+ * ```
+ *
+ * - `layerDefault('guard') = 'substitute'` — guards are lenient unless
+ *   EXPLICITLY overridden; they never inherit a scalar policy (a guard
+ *   reading a display value must not hard-fail on a missing locale).
+ * - every other layer has no default, so it inherits the scalar, else
+ *   falls back to `'throw'` (today's behavior — zero breaking change).
+ *
+ * @public
+ */
+type OnMissing = 'substitute' | 'null' | 'throw';
+/**
+ * The contexts in which a multilingual field is resolved. Each can carry
+ * its own `onMissing` policy.
+ *
+ * - `read`       — ordinary app reads (`get`/`list`/query projection).
+ * - `guard`      — a guard callback reading a value.
+ * - `join`       — a joined record expanded onto a row.
+ * - `mv`         — materialized-view input.
+ * - `derivation` — derivation input.
+ * - `export`     — bundle/public-envelope export.
+ */
+type Layer = 'read' | 'guard' | 'join' | 'mv' | 'derivation' | 'export';
+/** Field-level policy: a single scalar, or a per-layer map. */
+type OnMissingPolicy = OnMissing | Partial<Record<Layer, OnMissing>>;
+/**
+ * Resolve the effective `OnMissing` for a layer from a field's declared
+ * policy. See module docs for the resolution rule.
+ */
+declare function resolvePolicy(onMissing: OnMissingPolicy | undefined, layer: Layer): OnMissing;
+
+/**
+ * i18nText schema type —
+ *
+ * `i18nText({ languages, required })` creates a descriptor for a
+ * multi-language content field whose value is stored as a
+ * `{ [locale]: string }` map (e.g. `{ en: 'Consulting', th: 'ที่ปรึกษา' }`).
+ *
+ * On put, the descriptor validates that required languages are present.
+ * On read (when a `locale` option is passed), the map is collapsed to the
+ * caller's locale string via the fallback chain.
+ *
+ * Design decisions
+ * ────────────────
+ *
+ * **Descriptor pattern (not a Zod type).**
+ * `i18nText()` returns a plain descriptor object used in the collection's
+ * `i18nFields` option — same pattern as `ref()` / `dictKey()`. This keeps
+ * `@noy-db/core` at zero runtime dependencies and avoids Zod v3 field-type
+ * constraints. TypeScript inference is handled via the descriptor's type.
+ *
+ * **Enforcement at the collection boundary.**
+ * The `required` option is checked by `Collection.put()` via the compartment's
+ * registered `i18nFields`. Failed validation throws `MissingTranslationError`
+ * — a distinct class from `SchemaValidationError` so callers can tell
+ * "wrong shape" from "missing translations".
+ *
+ * **Resolution is post-decryption.**
+ * Locale resolution happens AFTER `decryptRecord()`, as a pure in-memory
+ * transform. No additional crypto work is needed. The resolved record is
+ * returned in place of the stored one, with i18nText fields replaced by
+ * their locale-resolved strings.
+ *
+ * **`locale: 'raw'`.**
+ * Passing `{ locale: 'raw' }` skips resolution and returns the full
+ * `{ [locale]: string }` map — useful for bilingual exports, admin UIs,
+ * and any context where all translations must be visible at once.
+ *
+ * **Out of scope.**
+ * Pluralization, RTL rendering, date/number formatting, per-locale CRDT
+ * merging.
+ */
+
+/** Flatten an intersection into a single object literal for nicer hovers. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The stored shape of a multilingual field, inferred from its `required`
+ * mode — so the compiler forces you to handle an absent optional locale
+ * (`string | undefined`) instead of silently yielding `undefined`.
+ *
+ * Mirrors `i18nText({ languages, required })`:
+ * - `'all'` (default) — every locale required: `{ th: string; en: string }`
+ * - `'any'`           — every locale optional: `{ th?: string; en?: string }`
+ *   (the "at least one present" guarantee is runtime-only — not expressible
+ *   in TypeScript — so each key is optional)
+ * - `readonly L[]`    — listed locales required, the rest optional:
+ *   `I18nMap<'th'|'en', ['th']>` → `{ th: string; en?: string }`
+ *
+ * @example
+ * ```ts
+ * type Lang = 'th' | 'en'
+ * interface Contact {
+ *   name: I18nMap<Lang, 'any'>      // { th?: string; en?: string }
+ *   legalName: I18nMap<Lang, ['th']> // { th: string; en?: string }
+ *   slug: I18nMap<Lang>             // { th: string; en: string }
+ * }
+ * ```
+ *
+ * @public
+ */
+type I18nMap<Langs extends string, Required extends 'all' | 'any' | readonly Langs[] = 'all'> = Required extends 'all' ? Record<Langs, string> : Required extends 'any' ? Partial<Record<Langs, string>> : Required extends readonly (infer R extends Langs)[] ? Prettify<Record<R, string> & Partial<Record<Exclude<Langs, R>, string>>> : never;
+/**
+ * Options for `i18nText()`.
+ *
+ * `languages` declares the full set of supported locales. `required`
+ * controls which must be present on every `put()`.
+ *
+ * `autoTranslate` is the per-field opt-in for the `plaintextTranslator`
+ * hook. When `true` and a `plaintextTranslator` is configured
+ * on `createNoydb()`, missing translations are generated before `put()`.
+ * Default: `false`.
+ */
+interface I18nTextOptions {
+    /** All supported locale codes (BCP 47). */
+    readonly languages: readonly string[];
+    /**
+     * Which locales must be present on every `put()`.
+     *
+     * - `'all'`       — every declared language must be present.
+     * - `'any'`       — at least one declared language must be present.
+     * - `string[]`    — listed locales are required; others are optional.
+     */
+    readonly required: 'all' | 'any' | readonly string[];
+    /**
+     * Per-field opt-in for the `plaintextTranslator` hook.
+     * When `true`, missing required translations are auto-generated
+     * before `put()` if a translator is configured. Default: `false`.
+     */
+    readonly autoTranslate?: boolean;
+    /**
+     * What to do when this field is resolved to a locale that is absent.
+     * A single policy, or a per-layer map (read/guard/join/mv/derivation/
+     * export). Default `'throw'` — today's behavior, zero breaking change.
+     * See {@link OnMissingPolicy}.
+     *
+     * NOTE (current wiring): ALL layers are enforced — `read` (`get`/`list`),
+     * `guard`, `derivation`, `mv`, `join`, `export`. Guard / derivation
+     * `ctx.vault` reads resolve under their own layer policy (`guard` defaults to
+     * the lenient `'substitute'`). The `mv` layer fires for materialized views
+     * that declare `{ i18nLocale, i18nFields }` — UNION (group-key i18n fields
+     * resolve before the unified-row bucketing) and query-form (resolved in
+     * `GroupedAggregation.run` before `groupAndReduce`); grouping a raw i18n field
+     * without a locale throws. The `join` layer resolves a joined right-side i18n
+     * field to the query locale (`toArray({ locale })` or the vault default; raw
+     * when locale-less). The `export` layer fires for
+     * `exportStream`/`exportJSON({ resolveLabels })` — records collapse to the
+     * export locale.
+     */
+    readonly onMissing?: OnMissingPolicy;
+    /**
+     * Ordered preferred-substitute locales used when `onMissing` resolves
+     * to `'substitute'` and the target locale is absent. `'any'` as an
+     * element means "first non-empty value". A caller-supplied `fallback`
+     * at read time takes precedence over this declared list.
+     */
+    readonly substitute?: readonly string[];
+    /**
+     * #285 smart-substitute. When `true`, a missing-locale `substitute` walk that
+     * misses the explicit chain prefers the available locale whose script is
+     * nearest the target (same script, then Latin) rather than an arbitrary value
+     * — e.g. a missing Thai label prefers another Thai (or Latin) translation over
+     * an unreadable script. Default `false` (legacy first-non-empty behavior).
+     */
+    readonly smartSubstitute?: boolean;
+    /**
+     * Per-locale script enforcement (write-time). `'auto'` infers the
+     * allowed Unicode scripts per locale (asymmetric Latin tolerance); an
+     * object overrides per slot. Absent ⇒ no check. See `./script.ts`.
+     */
+    readonly script?: 'auto' | Partial<Record<string, readonly string[]>>;
+    /**
+     * What to do when a slot's value contains characters outside its
+     * allowed script set. Default `'reject'`.
+     */
+    readonly onScriptViolation?: 'reject' | 'filter' | 'warn';
+}
+/**
+ * Descriptor returned by `i18nText()`. Attach to the collection's
+ * `i18nFields` option:
+ *
+ * ```ts
+ * const lineItems = company.collection<LineItem>('line-items', {
+ *   i18nFields: {
+ *     description: i18nText({ languages: ['en', 'th'], required: 'all' }),
+ *   },
+ * })
+ * ```
+ */
+interface I18nTextDescriptor {
+    readonly _noydbI18nText: true;
+    readonly options: I18nTextOptions;
+}
+/**
+ * Create an `I18nTextDescriptor` for a multi-language content field.
+ *
+ * @param options  Language list + enforcement mode.
+ *
+ * @example
+ * ```ts
+ * i18nText({ languages: ['en', 'th'], required: 'all' })
+ * i18nText({ languages: ['en', 'th'], required: ['th'], autoTranslate: true })
+ * ```
+ */
+declare function i18nText(options: I18nTextOptions): I18nTextDescriptor;
+/** Runtime predicate for detecting an `I18nTextDescriptor`. */
+declare function isI18nTextDescriptor(x: unknown): x is I18nTextDescriptor;
+/**
+ * Validate that a value is a valid `{ [locale]: string }` map and that
+ * all required locales are present. Throws `MissingTranslationError`
+ * when the required constraint is violated.
+ *
+ * Called by `Collection.put()` for each registered `i18nField`.
+ *
+ * @param value       The raw field value from the record being put.
+ * @param field       The field name (used in the thrown error message).
+ * @param descriptor  The `i18nText()` descriptor for this field.
+ */
+declare function validateI18nTextValue(value: unknown, field: string, descriptor: I18nTextDescriptor): void;
+/**
+ * Resolve an i18nText value (`{ [locale]: string }` map) to a string
+ * for the given locale.
+ *
+ * @param value    The stored locale map.
+ * @param locale   The requested locale code, or `'raw'` to return the map.
+ * @param fallback Single locale or ordered list; use `'any'` as the last
+ *                 element to fall back to any available translation.
+ * @param field    Field name used in `LocaleNotSpecifiedError` messages.
+ * @returns The resolved string, OR the original map when `locale === 'raw'`.
+ */
+/** Options for the policy-aware form of {@link resolveI18nText}. */
+interface ResolveI18nOptions {
+    /** Effective policy for the resolution layer. Default `'throw'`. */
+    readonly policy?: OnMissing;
+    /** Declared substitute chain; applied only under policy `'substitute'`. */
+    readonly substitute?: readonly string[];
+    /**
+     * #285 smart-substitute. When `true` and policy is `'substitute'`, after the
+     * explicit chain misses, pick the available locale whose script is nearest the
+     * target (same script first, then Latin's broad readability) instead of an
+     * arbitrary value. Default `false`.
+     */
+    readonly smartSubstitute?: boolean;
+}
+declare function resolveI18nText(value: Record<string, string>, locale: string, fallback?: string | readonly string[], field?: string): string | Record<string, string>;
+declare function resolveI18nText(value: Record<string, string>, locale: string, fallback: string | readonly string[] | undefined, field: string | undefined, opts: ResolveI18nOptions): string | Record<string, string> | null;
+/**
+ * Return all leaf values at `path`, expanding `[].` array wildcards.
+ *
+ * - `'name'`              → `[obj.name]`
+ * - `'address.lineOne'`   → `[obj.address.lineOne]`
+ * - `'contacts[].title'`  → `[obj.contacts[0].title, obj.contacts[1].title, …]`
+ *
+ * Returns an empty array when the path does not resolve (missing key,
+ * wrong type, etc.). Used by `enforceI18nOnPut` to validate nested fields.
+ */
+declare function getAtPath(obj: Record<string, unknown>, path: string): unknown[];
+/**
+ * Mutate `obj` in-place, setting `value` at the nested `path`.
+ * Supports dot notation (`'address.lineOne'`) but not array wildcards —
+ * auto-translate on `contacts[].title` style paths is not supported.
+ */
+declare function setAtPathInPlace(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Apply locale resolution to a single record, returning a new copy.
+ *
+ * For each field registered as an `i18nText` descriptor:
+ * - If `locale === 'raw'`, the field value is left as the stored map.
+ * - Otherwise, the field value is replaced with the resolved string.
+ *
+ * Field paths support dot notation (`'address.lineOne'`) and array
+ * wildcards (`'contacts[].title'`). Top-level fields work as before.
+ *
+ * @param record      The decrypted record.
+ * @param i18nFields  Map of field path → `I18nTextDescriptor`.
+ * @param locale      The requested locale (or `'raw'`).
+ * @param fallback    Fallback chain (optional).
+ * @param layer       Resolution layer (default `'read'`). Each field's
+ *                    `onMissing` policy is resolved for this layer, so the
+ *                    same record resolves leniently on a get but strictly
+ *                    inside an mv/derivation.
+ */
+declare function applyI18nLocale(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, locale: string, fallback?: string | readonly string[], layer?: Layer): Record<string, unknown>;
+
 /**
  * Query DSL `.groupBy()` —.
  *
@@ -649,8 +948,20 @@ declare class GroupedAggregation<R> {
      *. Present when the grouping field is a dictKey.
      */
     dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined);
-    /** Execute the query, group, reduce, and return an array of rows. */
-    run(): R[];
+    /**
+     * Execute the query, group, reduce, and return an array of rows.
+     *
+     * `opts` (#285 query-form MV grouping): when a `locale` + `i18nFields` are
+     * given, the declared group-key `i18nText` fields are resolved to that locale
+     * at the `mv` layer BEFORE bucketing — so an i18n group key is a stable string
+     * instead of a raw `{locale}` map. The MV executor passes the MV's
+     * `i18nLocale`/`i18nFields`; ordinary `.run()` callers pass nothing and are
+     * unaffected.
+     */
+    run(opts?: {
+        locale?: string;
+        i18nFields?: Record<string, I18nTextDescriptor>;
+    }): R[];
     /**
      * Execute the query, group, reduce, and resolve `<field>Label` for
      * each result row when the grouping field is a `dictKey` and a
@@ -736,4 +1047,4 @@ interface AggregateStrategy {
     scanAggregate<Spec extends AggregateSpec>(iter: AsyncIterable<unknown>, spec: Spec): Promise<AggregateResult<Spec>>;
 }
 
-export { type AggregateStrategy as A, MoneyUnsupportedError as B, isMoneyDescriptor as C, money as D, GROUPBY_MAX_CARDINALITY as G, type LiveAggregation as L, MoneyCurrencyError as M, type Reducer as R, type AggregateResult as a, type AggregateSpec as b, Aggregation as c, type AggregationUpstream as d, GROUPBY_WARN_CARDINALITY as e, GroupedAggregation as f, GroupedQuery as g, GroupedQueryN as h, type GroupedRow as i, type GroupedRowN as j, type ReducerOptions as k, avg as l, buildLiveAggregation as m, count as n, groupAndReduce as o, max as p, min as q, reduceRecords as r, resetGroupByWarnings as s, sum as t, type RoundingMode as u, type MoneyDescriptor as v, type MoneyOptions as w, type MoneyOptionsFixed as x, type MoneyOptionsMulti as y, MoneyPrecisionError as z };
+export { type AggregateStrategy as A, count as B, groupAndReduce as C, max as D, min as E, reduceRecords as F, GROUPBY_MAX_CARDINALITY as G, resetGroupByWarnings as H, type I18nMap as I, sum as J, type RoundingMode as K, type Layer as L, MoneyCurrencyError as M, type MoneyDescriptor as N, type OnMissing as O, type MoneyOptions as P, type MoneyOptionsFixed as Q, type ResolveI18nOptions as R, type MoneyOptionsMulti as S, MoneyPrecisionError as T, MoneyUnsupportedError as U, isMoneyDescriptor as V, money as W, type I18nTextDescriptor as a, type I18nTextOptions as b, type OnMissingPolicy as c, applyI18nLocale as d, isI18nTextDescriptor as e, resolvePolicy as f, getAtPath as g, type AggregateResult as h, i18nText as i, type AggregateSpec as j, Aggregation as k, type AggregationUpstream as l, GROUPBY_WARN_CARDINALITY as m, GroupedAggregation as n, GroupedQuery as o, GroupedQueryN as p, type GroupedRow as q, resolveI18nText as r, setAtPathInPlace as s, type GroupedRowN as t, type LiveAggregation as u, validateI18nTextValue as v, type Reducer as w, type ReducerOptions as x, avg as y, buildLiveAggregation as z };