@jarenjs/linq 0.49.2 → 0.56.0

package/types/jslt.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Hand-authored declarations for `@jarenjs/linq/jslt` — the JSLT pen's
+ * type contract, kept to the same line as `index.d.ts`: the common path
+ * is precisely typed, the exotic path is honestly `unknown`, nothing is
+ * ever a WRONG type.
+ *
+ * A body's VALUE is typed by annotating the callback's first argument
+ * (`(v: Expr<Book>) => …`) or by the rule's `schema` match when it is a
+ * schema-pen builder; without either it is the honest top. A body's
+ * externals are `root` and `path` — always present, no declaration —
+ * plus the parameters the body declares by name (`{ externals: ['rate']
+ * }`): a declared name types as `UnknownExpr` until the second argument
+ * is annotated (`x: Externals<{ rate: number }>`), an undeclared name is
+ * a compile error, as with the chain's `params()`.
+ *
+ * The honest limits: a rule's OUTPUT is the unwrapped shape of what its
+ * body returns, with every `apply()` — a dispatch to OTHER rules —
+ * `unknown`; a stylesheet's `In`/`Out` are its FIRST rule's (write the
+ * root rule first, as Appendix A does), or what the author annotates
+ * (`stylesheet<In, Out>(…)`). The built-in rule's rebuilds (`share`/
+ * `fresh` around an unmatched container) are not typed at all: a
+ * stylesheet whose root is unmatched is `Stylesheet<unknown, unknown>`
+ * unless annotated. Every claim here has a runtime twin in
+ * `test/linq/jslt-pen.test.js` and a compile-level pin in
+ * `test/consumer/linq-jslt.ts`.
+ */
+
+import type { ExprBase, MemberExpr, StringExpr, UnknownExpr, Unwrap } from './index.js';
+import type { BuilderLike, Json, JsonSchema } from './schema.js';
+
+/** A mode's built-in-rule disposition (JSLT-FORMAT §5). */
+export type Disposition = 'share' | 'fresh' | 'error';
+
+/**
+ * The externals a body may name: the two the engine binds on every
+ * dispatch (§8.2) and the parameters the body declared (§8.1).
+ */
+export type Externals<X = {}, Root = unknown> = {
+  /** The input document root (`$root`). */
+  readonly root: MemberExpr<Root>;
+  /** The matched value's normalized path (`$path`) — `null` for a location-less value. */
+  readonly path: StringExpr;
+} & {
+  readonly [K in keyof X & string]-?: MemberExpr<X[K]>;
+};
+
+/** Any expression-ish callback result the capture accepts. */
+export type BodyResult = ExprBase<unknown> | object | string | number | boolean | null;
+
+/** The value phantom of an expression type; the honest top otherwise. */
+export type ValueOf<V> = V extends ExprBase<infer T> ? (unknown extends T ? unknown : T) : unknown;
+
+/**
+ * A rule body's document — plain JSON (the `$expr` of a rule), carrying
+ * the value it was captured over and the shape it produces as
+ * phantoms. `body()` writes one; `rule()` reads both phantoms.
+ */
+export type BodyDocument<In = unknown, Out = unknown> = Json & {
+  /** Phantoms: declared, never present at runtime. */
+  readonly __in: In;
+  readonly __out: Out;
+};
+
+export interface BodyOptions<N extends string> {
+  /** The stylesheet parameters this body names (§8.1); `root` and `path` need none. */
+  readonly externals?: readonly N[];
+}
+
+/**
+ * Capture one rule body over the matched value at `$`. Type the value
+ * by annotating `v` (`(v: Expr<Book>) => …`); declare parameters by
+ * name and type them by annotating `x` (`x: Externals<{ rate: number
+ * }>`) — an undeclared name on `x` does not compile.
+ */
+export function body<
+  V extends ExprBase<unknown> = UnknownExpr,
+  N extends string = never,
+  R extends BodyResult = BodyResult,
+  Root = unknown,
+  X extends Record<N, unknown> = Record<N, unknown>,
+>(
+  fn: (value: V, x: Externals<X, Root>) => R,
+  options?: BodyOptions<N>,
+): BodyDocument<ValueOf<V>, Unwrap<R>>;
+
+/**
+ * `{ $apply: selector }` / `{ $apply: [selector, mode] }` — the
+ * apply-templates operator (§6), inside a `body()` callback. Its result
+ * is a dispatch to other rules, so it is the honest top: as an array
+ * element (`[apply(…)]`, the `[]` idiom) it unwraps to `unknown[]`; as a
+ * bare object member it is refused at build time (`JL0102`).
+ */
+export function apply(selector: ExprBase<unknown> | string | Json, mode?: string): UnknownExpr;
+
+/**
+ * `{ [name]: operands }` — a registered operator (§13), spelled without
+ * judging it; the engine's compiler decides. Works in any capture.
+ */
+export function op(name: `$${string}`, operands?: ExprBase<unknown> | Json | readonly (ExprBase<unknown> | Json)[]): UnknownExpr;
+
+/** The `match` member (§3): a JSONPath string, `{ path?, schema? }`, or `null` for the unconditional rule. */
+export type Match =
+  | string
+  | null
+  | undefined
+  | { readonly path?: string; readonly schema?: BuilderLike | JsonSchema | boolean };
+
+/** The value a match types: a schema-pen builder's `Infer<>`; the honest top otherwise. */
+export type MatchIn<M> = M extends { readonly schema: BuilderLike<infer O, any, any> } ? O : unknown;
+
+export interface RuleOptions {
+  /** The rule's mode (§7); the unnamed mode `""` by default. */
+  readonly mode?: string;
+  /** Explicit conflict resolution (§4); the three defaults otherwise. */
+  readonly priority?: number;
+}
+
+/** The `match` member as emitted. */
+export type MatchDocument =
+  | string
+  | { readonly path?: string; readonly schema?: JsonSchema | boolean };
+
+/** A rule as a plain document — what `stylesheet()` takes, by pen or by hand. */
+export interface RuleDocument {
+  readonly mode?: string;
+  readonly match?: MatchDocument;
+  readonly priority?: number;
+  readonly body: Json;
+}
+
+/** One template rule (§2.2), carrying its body's phantoms. */
+export interface Rule<In = unknown, Out = unknown> extends RuleDocument {
+  readonly __in: In;
+  readonly __out: Out;
+}
+
+/** A callback rule: the value is typed by annotating it (`(v: Expr<Book>) => …`)
+ * or by the match's schema builder; the honest top otherwise. */
+export function rule<
+  M extends Match,
+  R extends BodyResult,
+  V extends ExprBase<unknown> = MemberExpr<MatchIn<M>>,
+>(
+  match: M,
+  fn: (value: V, x: Externals<{}, unknown>) => R,
+  options?: RuleOptions,
+): Rule<ValueOf<V>, Unwrap<R>>;
+/** A `body()` document: its phantoms are the rule's (the match's schema types `In` when the body is untyped). */
+export function rule<M extends Match, In, Out>(
+  match: M,
+  body: BodyDocument<In, Out>,
+  options?: RuleOptions,
+): Rule<unknown extends In ? MatchIn<M> : In, Out>;
+/** A query document verbatim: nothing is inferred. */
+export function rule(match: Match, body: Json, options?: RuleOptions): Rule<unknown, unknown>;
+
+export interface StylesheetOptions {
+  /** The default disposition of every mode (§2.1, §5). */
+  readonly unmatched?: Disposition;
+  /** Per-mode overrides. */
+  readonly modes?: { readonly [mode: string]: { readonly unmatched: Disposition } };
+}
+
+/** The envelope (§2.1), carrying the root rule's phantoms. */
+export interface Stylesheet<In = unknown, Out = unknown> {
+  readonly __in: In;
+  readonly __out: Out;
+  readonly $jslt: '0.1';
+  readonly unmatched?: Disposition;
+  readonly modes?: { readonly [mode: string]: { readonly unmatched: Disposition } };
+  readonly rules: readonly RuleDocument[];
+}
+
+/** A rule's `In` phantom; a hand-written rule is `unknown`. */
+export type RuleIn<R> = R extends Rule<infer I, any> ? I : unknown;
+/** A rule's `Out` phantom; a hand-written rule is `unknown`. */
+export type RuleOut<R> = R extends Rule<any, infer O> ? O : unknown;
+
+/** The envelope over rule documents; `In`/`Out` are the FIRST rule's. */
+export function stylesheet<const R extends readonly RuleDocument[]>(
+  rules: R,
+  options?: StylesheetOptions,
+): Stylesheet<RuleIn<R[0]>, RuleOut<R[0]>>;
+/** The envelope with the phantoms as the author states them. */
+export function stylesheet<In, Out>(
+  rules: readonly RuleDocument[],
+  options?: StylesheetOptions,
+): Stylesheet<In, Out>;
+
+/** The input a stylesheet (or rule) was written over. */
+export type Input<S> = S extends { readonly __in: infer I } ? I : unknown;
+/** The shape a stylesheet (or rule) produces. */
+export type Output<S> = S extends { readonly __out: infer O } ? O : unknown;

package/types/migration.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Hand-authored declarations for `@jarenjs/linq/migration` — the
+ * migration pen's type contract, on the line every pen keeps: the common
+ * path precisely typed, the exotic path honestly `unknown`, nothing ever
+ * a WRONG type.
+ *
+ * A transform is typed from the two model documents' phantoms. `from`
+ * gives the OLD shape of the named table (`InferMeta<typeof
+ * previous>[name]['doc']`), the value the callback is captured over;
+ * `to` gives the NEW shape, which the callback's result must SPELL — a
+ * member forgotten, mistyped or not in the new shape is a compile error,
+ * and the honest top (`UnknownExpr`, a `get()`) is admitted wherever a
+ * precise value is, because the runtime validator is the judge there.
+ * From a JSON snapshot the old shape is `unknown` and the value the
+ * honest top; the author annotates it (`(u: Expr<User>) => …`) from the
+ * declaration `jaren-db snapshot --types` writes, or keeps the previous
+ * model module beside the current one so the phantom is there. An
+ * assertion's row is typed by the members the two shapes SHARE (a
+ * precondition sees old rows, a postcondition new ones; what both agree
+ * on is what neither lies about), annotated when one shape is meant.
+ * Every claim here has a runtime twin in
+ * `test/linq/migration-pen.test.js` and a compile-level pin in
+ * `test/consumer/linq-migration.ts`.
+ */
+
+import type { BoolExpr, DateTime, ExprBase, MemberExpr, UnknownExpr } from './index.js';
+import type { Json } from './schema.js';
+import type { ModelDocument, InferMeta } from './model.js';
+import type { Externals, RuleDocument, RuleOut, ValueOf } from './jslt.js';
+
+// ————— the document —————
+
+export interface DdlStep { readonly kind: 'ddl'; readonly sql: string; readonly note?: string }
+export interface SqlStep { readonly kind: 'sql'; readonly sql: string; readonly note?: string }
+export interface JsltStep {
+  readonly kind: 'jslt';
+  readonly collection: string;
+  readonly stylesheet: readonly RuleDocument[];
+  /** A planner placeholder; the runner refuses it (`JD0021`). The pen never sets or clears it. */
+  readonly draft?: boolean;
+  readonly note?: string;
+}
+export interface QueryStep {
+  readonly kind: 'query';
+  readonly collection: string;
+  readonly assert: Json;
+  readonly expect?: 'empty' | 'ebv';
+  readonly note?: string;
+}
+export interface DeriveColumn {
+  readonly name: string;
+  readonly derive: 'geohash' | 'bbox' | 'vector';
+  readonly precision?: number;
+  readonly dims?: number;
+  readonly component?: 'w' | 's' | 'e' | 'n';
+  readonly segments: readonly object[];
+}
+export interface DeriveStep {
+  readonly kind: 'derive';
+  readonly collection: string;
+  readonly columns: readonly DeriveColumn[];
+  readonly note?: string;
+}
+export interface RebuildStep {
+  readonly kind: 'rebuild';
+  readonly table: string;
+  readonly create: readonly string[];
+  readonly copy: string;
+  readonly indexes: readonly string[];
+  readonly note?: string;
+}
+export type MigrationStep = DdlStep | SqlStep | JsltStep | QueryStep | DeriveStep | RebuildStep;
+
+/** The `$migration` 0.1 document (MIGRATION-FORMAT §2). */
+export interface MigrationDocument {
+  readonly $migration: '0.1';
+  readonly id: string;
+  readonly from: string;
+  readonly to: string;
+  readonly note?: string;
+  readonly steps: readonly MigrationStep[];
+}
+
+// ————— what a model document types —————
+
+/** The entities and collections a model document declares; any string
+ * for a document the type cannot read (a JSON snapshot). */
+export type DeclaredNames<M> = M extends ModelDocument<infer E, infer C>
+  ? (unknown extends E ? string : keyof E & string) | (unknown extends C ? string : keyof C & string)
+  : string;
+
+/** The document shape of table `N` in a model — an entity's `doc`; the
+ * honest `unknown` for a collection, a JSON snapshot, or a name the
+ * model does not type. */
+export type DocOf<M, N extends string> =
+  [InferMeta<M>] extends [never] ? unknown
+    : N extends keyof InferMeta<M>
+      ? (InferMeta<M>[N] extends { doc: infer D } ? D : unknown)
+      : unknown;
+
+/** How a value of `T` is spelled in a transform's result: the value
+ * itself, an expression yielding it, the honest top, or — for an object
+ * — a literal spelling each member the same way; `unknown` admits
+ * anything. */
+export type Spell<T> = SpellPresent<Exclude<T, undefined>> | (undefined extends T ? undefined : never);
+type SpellPresent<T> =
+  unknown extends T ? unknown :
+  [T] extends [DateTime] ? string | ExprBase<string> | UnknownExpr :
+  [T] extends [readonly (infer E)[]] ? T | ExprBase<T> | UnknownExpr | readonly Spell<E>[] :
+  [T] extends [object] ? T | ExprBase<T> | UnknownExpr | { readonly [K in keyof T]: Spell<T[K]> } :
+  T | ExprBase<T> | UnknownExpr;
+
+/** A rules array's verdict: a typed first rule must produce the new
+ * shape; a hand-written rule (`unknown` out) is the honest top. */
+export type RulesFor<R extends readonly RuleDocument[], New> =
+  unknown extends RuleOut<R[0]> ? unknown : RuleOut<R[0]> extends New ? unknown : never;
+
+/** Any stylesheet envelope: the JSLT pen's (phantoms and all) or a hand-written one. */
+export type StylesheetLike = { readonly $jslt: '0.1'; readonly rules: readonly RuleDocument[] };
+
+/** A stylesheet's verdict: a typed one must produce the new shape; an
+ * untyped or hand-written one is the honest top. */
+export type SheetFor<S, New> = S extends { readonly __out: infer O }
+  ? (unknown extends O ? unknown : O extends New ? unknown : never)
+  : unknown;
+
+export interface AssertOptions {
+  /** `'empty'` (the default, absent from the document): no row may
+   * satisfy the predicate — it names the violation; `'ebv'`: the matching
+   * rows are the witness. */
+  readonly expect?: 'empty' | 'ebv';
+}
+
+// ————— the builder —————
+
+/** The migration under construction: immutable, every method a new
+ * builder; `.document`/`toJSON()` the deep-frozen document. */
+export class Migration<From = unknown, To = unknown> {
+  private constructor();
+  /** One rendered DDL statement (`ddl`). */
+  ddl(sql: string, note?: string): Migration<From, To>;
+  /** One data statement spelled directly (`sql`, MIGRATION-FORMAT §9.4). */
+  sql(sql: string, note?: string): Migration<From, To>;
+  /** A `jslt` step: one root rule captured over the OLD row (`root`/`path`
+   * as externals), whose result spells the NEW row. Over a planned
+   * document it replaces the draft for `name`; otherwise it is appended
+   * for a table the target declares. */
+  transform<N extends DeclaredNames<To>, V extends ExprBase<unknown> = MemberExpr<DocOf<From, N>>>(
+    name: N,
+    rule: (row: V, x: Externals<{}, ValueOf<V>>) => Spell<DocOf<To, N>>,
+  ): Migration<From, To>;
+  /** A `stylesheet(…)` document — its output must be the new row when it
+   * is typed; a hand-written envelope is the honest top. A disposition or
+   * a mode table cannot ride in a `jslt` step (`JL0102`). */
+  transform<N extends DeclaredNames<To>, S extends StylesheetLike>(
+    name: N,
+    stylesheet: S & SheetFor<S, DocOf<To, N>>,
+  ): Migration<From, To>;
+  /** A rules array: a typed first rule must produce the new row; a
+   * hand-written rule is the honest top. */
+  transform<N extends DeclaredNames<To>, const R extends readonly RuleDocument[]>(
+    name: N,
+    rules: R & RulesFor<R, DocOf<To, N>>,
+  ): Migration<From, To>;
+  /** A `query` step over `name`'s rows: the predicate names the VIOLATION
+   * (`expect: 'empty'`, the default) or the witness (`'ebv'`); the row is
+   * the members the two shapes share, annotated when one shape is meant. */
+  assert<N extends DeclaredNames<To>, V extends ExprBase<unknown> = MemberExpr<DocOf<From, N> | DocOf<To, N>>>(
+    name: N,
+    predicate: (row: V) => BoolExpr | boolean,
+    options?: AssertOptions,
+  ): Migration<From, To>;
+  /** A query document over the rows, verbatim. */
+  assert<N extends DeclaredNames<To>>(name: N, query: Json, options?: AssertOptions): Migration<From, To>;
+  /** A backfill of stored derived columns (`derive`, §2.1). */
+  derive<N extends DeclaredNames<To>>(name: N, columns: readonly DeriveColumn[]): Migration<From, To>;
+  /** Any planner-emitted step, verbatim — the escape that keeps `rebuild` authorable. */
+  step(raw: MigrationStep): Migration<From, To>;
+  readonly document: MigrationDocument;
+  toJSON(): MigrationDocument;
+}
+
+export interface MigrationSpec<From, To> {
+  readonly id: string;
+  /** The model the store is at: a model document (the pen's or a JSON snapshot). */
+  readonly from: From;
+  /** The model the code carries. */
+  readonly to: To;
+  readonly note?: string;
+}
+
+/** A migration between two model documents; `from`/`to` are their shape hashes. */
+export function defineMigration<From extends object, To extends object>(spec: MigrationSpec<From, To>): Migration<From, To>;
+
+/** A planner's document, taken up so a typed `transform` replaces the
+ * draft it left; `from`/`to` type the transforms and are checked against
+ * the document's hashes (`JL0102` when they are not the planned models). */
+export function fromPlanned<From = unknown, To = unknown>(
+  document: MigrationDocument | Json,
+  options?: { readonly from?: From; readonly to?: To },
+): Migration<From, To>;