@jarenjs/linq 0.67.0 → 0.72.2

package/src/schema/builders.js

@@ -33,14 +33,9 @@ const NAME_RE = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
  * document asserts: `meta()` refuses them so an annotation is never a
  * back door around a builder.
  *
- * The two kinds are not the same size. 44 of these have a builder method
- * that emits them; the other 25 — `not`, the unevaluated pair,
- * `dependentSchemas`/`dependencies`, the `contains` bounds, the content
- * family, the four format bounds, the identification and dynamic-
- * reference families, `definitions`, `additionalItems` and `$data` — are
- * owned only by the second clause, and are written with `keyword()` or
- * `from()`. SCHEMA-PEN.md §6.2 lists them and `test/linq/schema-pen.test.js`
- * holds that list equal to this set.
+ * Each owned name has an executable dedicated emission route. The keyword
+ * census checks exact spellings, including the explicit legacy nullable
+ * spelling, independently of the normalized nullable() union.
  */
 const OWNED = new Set([
   '$schema', '$id', '$ref', '$defs', 'definitions', '$anchor', '$dynamicRef',
@@ -151,6 +146,36 @@ function annotate(annotations, key, value) {
   return Object.freeze(next);
 }
 
+/** @param {any} value @param {string} what */
+function requireBoolean(value, what) {
+  if (typeof value === 'boolean') return value;
+  throw new LinqBuildError('JL0101', `${what} takes a boolean`);
+}
+
+/** Own-key maps preserve computed `__proto__` names. */
+function valueMap(map, what, accept) {
+  if (map === null || typeof map !== 'object' || Array.isArray(map))
+    throw new LinqBuildError('JL0101', `${what} takes a plain object`);
+  requireNameMap(map, what);
+  return Object.fromEntries(Object.keys(map).map((key) => [key, accept(map[key], `${what}.${key}`)]));
+}
+
+/** Keep builder identity while snapshotting JSON containers. */
+function snapshotKeyword(value, seen = new Set()) {
+  if (isSchemaBuilder(value)) return value;
+  if (value === null || typeof value !== 'object') return requireJson(value, 'keyword()');
+  if (seen.has(value)) throw new LinqBuildError('JL0101', 'keyword() received a cycle, which is not JSON');
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) result = Array.from(value, (v) => snapshotKeyword(v, seen));
+  else {
+    requireNameMap(value, 'keyword()');
+    result = Object.fromEntries(Object.keys(value).map((key) => [key, snapshotKeyword(value[key], seen)]));
+  }
+  seen.delete(value);
+  return Object.freeze(result);
+}
+
 /** The state every kind shares. @param {string} kind @param {object} own */
 export function initial(kind, own) {
   return Object.freeze({
@@ -200,6 +225,50 @@ export class SchemaBuilder {
   /** `JSON.stringify(builder)` is the document. */
   toJSON() { return this.schema; }
 
+  /** `$id`: the schema resource identifier. @param {string} uri */
+  id(uri) { return this.keyword('$id', requireString(uri, 'id()')); }
+
+  /** `$anchor`: emitted verbatim, without inferred reference identity. @param {string} value */
+  anchor(value) { return this.keyword('$anchor', requireString(value, 'anchor()')); }
+  /** `$dynamicRef`: emitted verbatim, without inferred reference identity. @param {string} value */
+  dynamicRef(value) { return this.keyword('$dynamicRef', requireString(value, 'dynamicRef()')); }
+  /** `$dynamicAnchor`: emitted verbatim, without inferred reference identity. @param {string} value */
+  dynamicAnchor(value) { return this.keyword('$dynamicAnchor', requireString(value, 'dynamicAnchor()')); }
+  /** `$recursiveRef`: emitted verbatim, without inferred reference identity. @param {string} value */
+  recursiveRef(value) { return this.keyword('$recursiveRef', requireString(value, 'recursiveRef()')); }
+  /** `$data`: emitted verbatim, without inferred reference identity. @param {string} value */
+  dollarData(value) { return this.keyword('$data', requireString(value, 'dollarData()')); }
+  /** `$recursiveAnchor`. @param {boolean} value */
+  recursiveAnchor(value) { return this.keyword('$recursiveAnchor', requireBoolean(value, 'recursiveAnchor()')); }
+  /** Legacy `nullable`, without a narrower phantom claim. @param {boolean} value */
+  legacyNullable(value) { return this.keyword('nullable', requireBoolean(value, 'legacyNullable()')); }
+  /** `$vocabulary`: URI → required flag. @param {Record<string, boolean>} map */
+  vocabulary(map) { return this.keyword('$vocabulary', valueMap(map, 'vocabulary()', requireBoolean)); }
+  /** `data`: keyword → instance pointer. @param {Record<string, string>} map */
+  data(map) { return this.keyword('data', valueMap(map, 'data()', requireString)); }
+  /** `not`: a validator assertion, without negating the phantom. @param {any} builder */
+  not(builder) { return this.keyword('not', requireBuilder(builder, 'not()')); }
+  /** `unevaluatedProperties`: annotation-dependent validation. @param {any} builder */
+  unevaluatedProperties(builder) { return this.keyword('unevaluatedProperties', requireBuilder(builder, 'unevaluatedProperties()')); }
+  /** `unevaluatedItems`: annotation-dependent validation. @param {any} builder */
+  unevaluatedItems(builder) { return this.keyword('unevaluatedItems', requireBuilder(builder, 'unevaluatedItems()')); }
+  /** `dependentSchemas`: member → schema. @param {Record<string, any>} map */
+  dependentSchemas(map) { return this.keyword('dependentSchemas', Object.fromEntries(requireBuilderMap(map, 'dependentSchemas()'))); }
+  /** Legacy schema definitions; named children retain shared `$defs` identity. @param {Record<string, any>} map */
+  definitions(map) { return this.keyword('definitions', Object.fromEntries(requireBuilderMap(map, 'definitions()'))); }
+  /** Legacy `additionalItems`; use with a draft-07 tuple. @param {any} builder */
+  additionalItems(builder) { return this.keyword('additionalItems', requireBuilder(builder, 'additionalItems()')); }
+  /** Legacy schema or required-member dependencies. @param {Record<string, any>} map */
+  dependencies(map) {
+    return this.keyword('dependencies', valueMap(map, 'dependencies()', (value, what) => {
+      if (!Array.isArray(value)) return requireBuilder(value, what);
+      const names = value.map((v) => requireString(v, what));
+      if (new Set(names).size !== names.length)
+        throw new LinqBuildError('JL0101', `${what} takes unique member names`);
+      return Object.freeze(names);
+    }));
+  }
+
   /** As an object member: left out of `required`. */
   optional() { return this.with({ optional: true }); }
 
@@ -323,12 +392,30 @@ export class SchemaBuilder {
    * @returns {this}
    */
   keyword(key, value) {
-    return this.with({ keywords: Object.freeze({ ...this.#state.keywords, [key]: value }) });
+    if ((this.state.kind === 'never' || (this.state.kind === 'raw' && typeof this.state.json === 'boolean'))
+      && !this.state.nullable) {
+      throw new LinqBuildError('JL0102', `a boolean schema carries no '${key}' — nullable() it first`);
+    }
+    return this.with({ keywords: Object.freeze({ ...this.#state.keywords, [key]: snapshotKeyword(value) }) });
   }
 }
 
 /** `{ type: 'string' }` and the string constraints. */
 export class StringBuilder extends SchemaBuilder {
+  /** `contentEncoding`. @param {string} value */
+  contentEncoding(value) { return this.keyword('contentEncoding', requireString(value, 'contentEncoding()')); }
+  /** `contentMediaType`. @param {string} value */
+  contentMediaType(value) { return this.keyword('contentMediaType', requireString(value, 'contentMediaType()')); }
+  /** `contentSchema`: annotation, with shared definition identity. @param {any} builder */
+  contentSchema(builder) { return this.keyword('contentSchema', requireBuilder(builder, 'contentSchema()')); }
+  /** `formatMinimum`. @param {string} value */
+  formatMinimum(value) { return this.keyword('formatMinimum', requireString(value, 'formatMinimum()')); }
+  /** `formatMaximum`. @param {string} value */
+  formatMaximum(value) { return this.keyword('formatMaximum', requireString(value, 'formatMaximum()')); }
+  /** `formatExclusiveMinimum`. @param {string} value */
+  formatExclusiveMinimum(value) { return this.keyword('formatExclusiveMinimum', requireString(value, 'formatExclusiveMinimum()')); }
+  /** `formatExclusiveMaximum`. @param {string} value */
+  formatExclusiveMaximum(value) { return this.keyword('formatExclusiveMaximum', requireString(value, 'formatExclusiveMaximum()')); }
   /** `minLength`. @param {number} n */
   min(n) { return this.keyword('minLength', requireCount(n, 'min()')); }
   /** `maxLength`. @param {number} n */
@@ -388,6 +475,10 @@ export class NumberBuilder extends SchemaBuilder {
 
 /** `{ type: 'array', items }` and the array constraints. */
 export class ArrayBuilder extends SchemaBuilder {
+  /** `minContains`. @param {number} n */
+  minContains(n) { return this.keyword('minContains', requireCount(n, 'minContains()')); }
+  /** `maxContains`. @param {number} n */
+  maxContains(n) { return this.keyword('maxContains', requireCount(n, 'maxContains()')); }
   /** `minItems`. @param {number} n */
   min(n) { return this.keyword('minItems', requireCount(n, 'min()')); }
   /** `maxItems`. @param {number} n */

package/src/schema/emit.js

@@ -118,7 +118,10 @@ export function reachesNormalizer(builder, seen = new Set()) {
   for (const [key] of st.annotations) {
     if (NORMALIZER_KEYS.includes(key)) return true;
   }
-  return children(st).some((child) => reachesNormalizer(child, seen));
+  const keywordChildren = (value) => isSchemaBuilder(value) ? reachesNormalizer(value, seen)
+    : value !== null && typeof value === 'object' && Object.values(value).some(keywordChildren);
+  return Object.values(st.keywords).some(keywordChildren)
+    || children(st).some((child) => reachesNormalizer(child, seen));
 }
 
 /** Every builder one state holds directly (lazy thunks resolved). */
@@ -215,6 +218,12 @@ function emitNode(builder, ctx, at) {
   const st = builder.state;
   let node = emitCore(builder, st, ctx, at);
   if (st.nullable) node = nullableOf(node, st);
+  for (const key of Object.keys(st.keywords)) {
+    const value = st.keywords[key];
+    setObjectMember(node, key, emitKeyword(value, ctx, `${at}/${token(key)}`, key));
+  }
+  if (st.nullable && TYPED[st.kind] !== undefined && Array.isArray(node.enum)
+    && !node.enum.includes(null)) node.enum = [...node.enum, null];
   if (st.checks.length > 0) {
     node.$query = st.checks.length === 1 ? st.checks[0] : { $and: st.checks };
   }
@@ -222,6 +231,19 @@ function emitNode(builder, ctx, at) {
   return node;
 }
 
+/** Emit schema-valued keywords in the root's shared definition context. */
+function emitKeyword(value, ctx, at, keyword) {
+  if (isSchemaBuilder(value)) {
+    if (['not', 'unevaluatedProperties', 'unevaluatedItems', 'dependentSchemas', 'dependencies', 'contentSchema'].includes(keyword))
+      refuseNormalizerUnder(value, keyword, at);
+    return emitNode(value, ctx, at);
+  }
+  if (Array.isArray(value)) return value.map((v, i) => emitKeyword(v, ctx, `${at}/${i}`, keyword));
+  if (value !== null && typeof value === 'object')
+    return Object.fromEntries(Object.keys(value).map((k) => [k, emitKeyword(value[k], ctx, `${at}/${token(k)}`, keyword)]));
+  return value;
+}
+
 /** Fold `null` into a typed node; wrap an untyped one in `anyOf`. */
 function nullableOf(node, st) {
   if (TYPED[st.kind] !== undefined) {
@@ -238,12 +260,6 @@ function nullableOf(node, st) {
   return { anyOf: [node, { type: 'null' }] };
 }
 
-/** The constraint keywords a builder collected, in the order set. */
-function withKeywords(node, st) {
-  for (const key of Object.keys(st.keywords)) node[key] = st.keywords[key];
-  return node;
-}
-
 /**
  * The kind-specific core of a node: `type` and the structural
  * keywords, with the collected constraints after them.
@@ -256,7 +272,7 @@ function withKeywords(node, st) {
 function emitCore(builder, st, ctx, at) {
   switch (st.kind) {
     case 'string': case 'number': case 'integer': case 'boolean': case 'null':
-      return withKeywords({ type: st.kind }, st);
+      return { type: st.kind };
     case 'literal':
       return { const: st.value };
     case 'enum':
@@ -293,20 +309,20 @@ function emitCore(builder, st, ctx, at) {
         node.propertyNames = emitNode(st.names, ctx, `${at}/propertyNames`);
       }
       if (st.dependent !== null) node.dependentRequired = cloneJson(st.dependent);
-      return withKeywords(node, st);
+      return node;
     }
     case 'record':
-      return withKeywords({
+      return {
         type: 'object',
         additionalProperties: emitNode(st.values, ctx, `${at}/additionalProperties`),
-      }, st);
+      };
     case 'array': {
       const node = { type: 'array', items: emitNode(st.items, ctx, `${at}/items`) };
       if (st.contains !== null) {
         refuseNormalizerUnder(st.contains, 'contains()', `${at}/contains`);
         node.contains = emitNode(st.contains, ctx, `${at}/contains`);
       }
-      return withKeywords(node, st);
+      return node;
     }
     case 'tuple': {
       const node = {
@@ -315,7 +331,7 @@ function emitCore(builder, st, ctx, at) {
       };
       if (st.rest !== null) node.items = emitNode(st.rest, ctx, `${at}/items`);
       node.minItems = st.items.length;
-      return withKeywords(node, st);
+      return node;
     }
     case 'union': case 'discriminated': {
       const keyword = st.kind === 'union' ? 'anyOf' : 'oneOf';

package/types/ai.d.ts

@@ -0,0 +1,56 @@
+import type { Json } from './schema.js';
+import type { ExprBase, UnknownExpr } from './index.js';
+export type Query = Json | ((value: UnknownExpr) => ExprBase<unknown> | Json);
+export interface ChunkOptions { readonly strategy?: 'size' | 'line' | 'separator'; readonly size?: number }
+export interface GrepOptions { readonly pattern: string; readonly flags?: 'i' | 'm' | 'im' | ''; readonly limit?: number }
+export interface AnswerOptions { readonly chars?: number }
+export interface ReduceOptions { readonly outputSchema?: Json }
+export interface StepOptions {
+  chunk: ChunkOptions; grep: GrepOptions; select: { readonly query: Json };
+  stat: {}; peek: {}; map: { readonly prompt: string }; reduce: { readonly query: Json } & ReduceOptions; answer: AnswerOptions;
+}
+export type Operation = keyof StepOptions;
+export type Step<K extends Operation, F extends string = string, N extends string = string> = {
+  readonly op: K; readonly from: F;
+} & (K extends 'answer' ? {} : { readonly as: N }) & StepOptions[K];
+export type StepDocument = { [K in Operation]: Step<K> }[Operation];
+export interface ProgramDocument { readonly steps: readonly StepDocument[] }
+export function chunk<const F extends string, const N extends string>(from: F, as: N, options?: ChunkOptions): Step<'chunk', F, N>;
+export function grep<const F extends string, const N extends string>(from: F, as: N, options: GrepOptions): Step<'grep', F, N>;
+export function select<const F extends string, const N extends string>(from: F, as: N, query: Query): Step<'select', F, N>;
+export function stat<const F extends string, const N extends string>(from: F, as: N): Step<'stat', F, N>;
+export function peek<const F extends string, const N extends string>(from: F, as: N): Step<'peek', F, N>;
+export function map<const F extends string, const N extends string>(from: F, as: N, prompt: string): Step<'map', F, N>;
+export function reduce<const F extends string, const N extends string>(from: F, as: N, query: Query, options?: ReduceOptions): Step<'reduce', F, N>;
+export function answer<const F extends string>(from: F, options?: AnswerOptions): Step<'answer', F>;
+
+type Kind = Exclude<Operation, 'answer'> | 'slot';
+type Bindings = Record<string, Kind>;
+type Names<B, K extends Kind = Kind> = { [N in keyof B]: B[N] extends K ? N : never }[keyof B] & string;
+type Single<B> = Names<B, Exclude<Kind, 'chunk' | 'map'>>;
+type Fresh<B, N extends string> = N extends keyof B ? B[N] extends 'slot' ? N : never : N;
+type Add<B, N extends string, K extends Kind> = Omit<B, N> & Record<N, K>;
+type InputFor<B, K extends Operation> = K extends 'reduce' ? Names<B, 'map'> : K extends 'select' | 'answer' ? Single<B> : Names<B>;
+type StepKeys<K extends Operation> = 'op' | 'from' | (K extends 'answer' ? never : 'as') | keyof StepOptions[K];
+type CheckStep<B, T extends StepDocument> = Exclude<keyof T, StepKeys<T['op']>> extends never ? T['from'] extends InputFor<B, T['op']>
+  ? T extends { readonly as: infer N extends string } ? N extends Fresh<B, N> ? unknown : never : unknown : never : never;
+type AfterStep<B, T extends StepDocument> = T extends { readonly as: infer N extends string; readonly op: infer K extends Kind } ? Add<B, N, K> : B;
+export class ProgramBuilder<B extends Bindings = {}, Done extends boolean = false> {
+  protected constructor();
+  readonly __bindings: B;
+  readonly __done: Done;
+  readonly schema: ProgramDocument;
+  toJSON(): ProgramDocument;
+  step<const T extends StepDocument>(this: ProgramBuilder<B, false>, step: T & CheckStep<B, T>): ProgramBuilder<AfterStep<B, T>, T['op'] extends 'answer' ? true : false>;
+  chunk<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>, options?: ChunkOptions): ProgramBuilder<Add<B, N, 'chunk'>>;
+  grep<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>, options: GrepOptions): ProgramBuilder<Add<B, N, 'grep'>>;
+  select<N extends string>(this: ProgramBuilder<B, false>, from: Single<B>, as: Fresh<B, N>, query: Query): ProgramBuilder<Add<B, N, 'select'>>;
+  stat<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>): ProgramBuilder<Add<B, N, 'stat'>>;
+  peek<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>): ProgramBuilder<Add<B, N, 'peek'>>;
+  map<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>, prompt: string): ProgramBuilder<Add<B, N, 'map'>>;
+  reduce<N extends string>(this: ProgramBuilder<B, false>, from: Names<B, 'map'>, as: Fresh<B, N>, query: Query, options?: ReduceOptions): ProgramBuilder<Add<B, N, 'reduce'>>;
+  answer(this: ProgramBuilder<B, false>, from: Single<B>, options?: AnswerOptions): ProgramBuilder<B, true>;
+}
+export function program<const S extends readonly string[] = []>(slots?: S): ProgramBuilder<Record<S[number], 'slot'>>;
+/** Raw documents make no binding-order or terminal-state inference. */
+export function from(document: ProgramDocument): ProgramBuilder<Record<string, Kind>, boolean>;