@coldsmirk/abacus-core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -313,9 +313,9 @@ interface FieldConditionInput {
   /**
    * The field path the operator tests. Emitted **verbatim** into the compiled
    * ZEN source as a path expression (guarded by an identifier-path pattern that
-   * also rejects ZEN reserved words such as `true` or `not` as segments), unlike
-   * `value`, which is serialized to a ZEN literal — so callers must supply a
-   * valid identifier path, not arbitrary user text.
+   * rejects keywords where ZEN cannot parse them as identifiers), unlike `value`,
+   * which is serialized to a ZEN literal — so callers must supply a valid
+   * identifier path, not arbitrary user text.
    */
   subject: string;
   operator: ConditionOperator;
@@ -382,8 +382,8 @@ declare function isZenRepresentableNumber(value: number): boolean;
  * {@link encodeZenString}; arrays become `[a, b, ...]`.
  *
  * Throws {@link ExpressionError} for a value with no faithful ZEN
- * representation — an object, symbol, or function, a string containing both
- * quote styles, a number failing {@link isZenRepresentableNumber} (outside
+ * representation — an object, symbol, or function, a string containing all
+ * three raw-string delimiters, a number failing {@link isZenRepresentableNumber} (outside
  * ZEN's decimal domain, or held differently by the engine's context
  * conversion), or a bigint outside the decimal domain. Callers that need a
  * sentinel instead of a throw go through {@link compileCondition}, which
@@ -630,6 +630,7 @@ declare const enMessages: ExpressionMessages;
  * Built-in Simplified Chinese message catalog.
  */
 declare const zhCNMessages: ExpressionMessages;
+type ExpressionMessagesListener = (messages: ExpressionMessages) => void;
 /**
  * Register (or replace) the message catalog for a locale key, making it selectable
  * via {@link configureExpressionMessages}. This is how a host adds a language the
@@ -663,6 +664,11 @@ declare function configureExpressionMessages({
  * The active {@link ExpressionMessages} catalog (English by default).
  */
 declare function getExpressionMessages(): ExpressionMessages;
+/**
+ * Subscribe to active message-catalog changes. Returns an idempotent unsubscribe
+ * function; listeners run synchronously after the new catalog becomes active.
+ */
+declare function subscribeExpressionMessages(listener: ExpressionMessagesListener): () => void;
 /**
  * One `{{ expression }}` hole located in a template document. `from` / `to` are
  * the character offsets of the inner expression itself — the text between the
@@ -729,4 +735,158 @@ declare function getTemplateDiagnosticsSync(source: string): ExpressionDiagnosti
  * Async {@link getTemplateDiagnosticsSync}, loading the engine on first use.
  */
 declare function getTemplateDiagnostics(source: string): Promise<ExpressionDiagnostic[]>;
-export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, MAX_CONDITION_TREE_DEPTH, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, emptyConditionGroup, enMessages, ensureConditionNodeIds, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, isZenRepresentableNumber, liftConditionTree, loadEngine, newConditionNodeId, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };
+/**
+ * The field-tree model behind the visual JSON Schema builder: a lossless projection of the
+ * JSON Schema subset the tree can host (`type` / `properties` / `items`, plus `required`).
+ * The schema JSON stays the single source of truth: {@link parseSchemaTree} REFUSES anything
+ * outside the subset (never a lossy rewrite), so a hand-written `oneOf` or `format` keeps its
+ * document JSON-only instead of silently vanishing on the first visual edit.
+ */
+/**
+ * The one dialect the tree round-trips: a document may omit `$schema` or declare exactly this.
+ */
+declare const SCHEMA_DIALECT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+type SchemaTreeFieldType = "any" | "array" | "boolean" | "integer" | "number" | "object" | "string";
+interface SchemaTreeField {
+  /**
+   * Stable row identity for React keys and targeted edits — a UI concern, never serialized.
+   */
+  id: string;
+  /**
+   * The property name under its parent object; unused on an array-element node.
+   */
+  name: string;
+  type: SchemaTreeFieldType;
+  /**
+   * Listed in the parent object's `required`; unused on an array-element node.
+   */
+  required: boolean;
+  /**
+   * The schema's `description` annotation; blank means none (not serialized).
+   */
+  description: string;
+  /**
+   * Sub-fields, meaningful when `type` is `object`.
+   */
+  children: SchemaTreeField[];
+  /**
+   * The element node, meaningful when `type` is `array`; `null` means untyped elements.
+   */
+  items: SchemaTreeField | null;
+  /**
+   * For an object or array node parsed from JSON, whether its source explicitly
+   * declared that type. `false` preserves a type-less applicator; omitted keeps the
+   * historical hand-built-tree default of emitting the type.
+   */
+  explicitType?: boolean;
+  /**
+   * Whether a blank / whitespace-only name came from a real `properties` key and must be
+   * persisted. Omitted blank names are unfinished UI rows and do not serialize.
+   */
+  preserveBlankName?: boolean;
+}
+interface SchemaTree {
+  fields: SchemaTreeField[];
+  /**
+   * Whether the source declared `$schema` (re-emitted verbatim on serialize).
+   */
+  dialect: boolean;
+  /**
+   * The root schema's `description` annotation, preserved verbatim across the round trip
+   * (the field view offers no root-level editor); blank means none.
+   */
+  description: string;
+  /**
+   * For a tree parsed from JSON, whether the root explicitly declared `type: "object"`.
+   * `false` preserves a type-less root; omitted keeps the historical hand-built-tree default
+   * of emitting the type.
+   */
+  explicitType?: boolean;
+}
+/**
+ * Why a document cannot be projected onto the field tree — structured so a UI can localize
+ * the explanation. Every code names the offending part where one exists.
+ */
+type SchemaTreeIssue = {
+  code: "invalid-description";
+} | {
+  code: "invalid-field-definition";
+  field: string;
+} | {
+  code: "invalid-field-type";
+  field: string;
+} | {
+  code: "invalid-json";
+} | {
+  code: "invalid-properties";
+} | {
+  code: "invalid-required";
+} | {
+  code: "misplaced-keyword";
+  keyword: string;
+  holder: "array" | "object";
+} | {
+  code: "root-not-object";
+} | {
+  code: "unknown-required-field";
+  field: string;
+} | {
+  code: "unsupported-dialect";
+} | {
+  code: "unsupported-field-type";
+  field: string;
+  type: string;
+} | {
+  code: "unsupported-keyword";
+  keyword: string;
+};
+type SchemaTreeParseResult = {
+  ok: true;
+  tree: SchemaTree;
+} | {
+  ok: false;
+  issue: SchemaTreeIssue;
+};
+/**
+ * A fresh {@link SchemaTreeField}, defaulting to an optional unnamed string field. The id is a
+ * tagged counter, not a UUID: field identity is a UI concern with no persistence or
+ * cross-process meaning — exactly the guarantee a React key needs.
+ */
+declare function newSchemaTreeField(overrides?: Partial<Omit<SchemaTreeField, "id">>): SchemaTreeField;
+/**
+ * The expression scope a schema tree declares: each named field becomes a typed variable, so a
+ * host can hand the result straight to `<ExpressionInput variables={…}>` (or `analyzeTypes`)
+ * and complete against the declared shape. Blank draft rows are skipped, while blank property
+ * names preserved by {@link parseSchemaTree} remain part of the scope.
+ */
+declare function schemaTreeToExpressionType(tree: SchemaTree): ExpressionType;
+/**
+ * Infer a draft 2020-12 JSON Schema from a sample payload — the "generate from example" path of
+ * the visual schema builder. Deliberately emits only the subset {@link parseSchemaTree} hosts
+ * (`type` / `properties` / `items`): integers stay `number` (a sample's `5` rarely promises
+ * integers forever) and nothing is marked `required` (validation strictness is an authoring
+ * decision, not something a single sample can attest).
+ */
+interface JsonObject {
+  [key: string]: Json;
+}
+type Json = null | boolean | number | string | Json[] | JsonObject;
+/**
+ * The schema a sample value attests: scalars map to their type, objects carry every observed
+ * property, arrays take the merged schema of their elements (an empty or mixed array leaves the
+ * items open). `null` says nothing about the real type, so it infers `{}` (any).
+ */
+declare function inferSchema(sample: Json): JsonObject;
+/**
+ * Project a schema document onto the field tree, or refuse with a structured
+ * {@link SchemaTreeIssue} when it uses anything beyond the subset. A blank document parses as
+ * an empty tree.
+ */
+declare function parseSchemaTree(text: string): SchemaTreeParseResult;
+/**
+ * The field tree back as pretty-printed schema JSON. A parsed type-less object root stays
+ * type-less; a hand-built tree still emits an object root by default. Clearing the contract
+ * entirely (an empty document) stays a source-mode action.
+ */
+declare function serializeSchemaTree(tree: SchemaTree): string;
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMessagesListener, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type Json, type LoadEngineOptions, MAX_CONDITION_TREE_DEPTH, SCHEMA_DIALECT_2020_12, type SchemaTree, type SchemaTreeField, type SchemaTreeFieldType, type SchemaTreeIssue, type SchemaTreeParseResult, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, emptyConditionGroup, enMessages, ensureConditionNodeIds, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, inferSchema, isEngineReady, isZenRepresentableNumber, liftConditionTree, loadEngine, newConditionNodeId, newSchemaTreeField, parseSchemaTree, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, schemaTreeToExpressionType, selectBranch, selectBranchWith, serializeSchemaTree, subscribeExpressionMessages, templateHoleAt, toZenLiteral, zhCNMessages };

package/dist/index.d.ts

@@ -313,9 +313,9 @@ interface FieldConditionInput {
   /**
    * The field path the operator tests. Emitted **verbatim** into the compiled
    * ZEN source as a path expression (guarded by an identifier-path pattern that
-   * also rejects ZEN reserved words such as `true` or `not` as segments), unlike
-   * `value`, which is serialized to a ZEN literal — so callers must supply a
-   * valid identifier path, not arbitrary user text.
+   * rejects keywords where ZEN cannot parse them as identifiers), unlike `value`,
+   * which is serialized to a ZEN literal — so callers must supply a valid
+   * identifier path, not arbitrary user text.
    */
   subject: string;
   operator: ConditionOperator;
@@ -382,8 +382,8 @@ declare function isZenRepresentableNumber(value: number): boolean;
  * {@link encodeZenString}; arrays become `[a, b, ...]`.
  *
  * Throws {@link ExpressionError} for a value with no faithful ZEN
- * representation — an object, symbol, or function, a string containing both
- * quote styles, a number failing {@link isZenRepresentableNumber} (outside
+ * representation — an object, symbol, or function, a string containing all
+ * three raw-string delimiters, a number failing {@link isZenRepresentableNumber} (outside
  * ZEN's decimal domain, or held differently by the engine's context
  * conversion), or a bigint outside the decimal domain. Callers that need a
  * sentinel instead of a throw go through {@link compileCondition}, which
@@ -630,6 +630,7 @@ declare const enMessages: ExpressionMessages;
  * Built-in Simplified Chinese message catalog.
  */
 declare const zhCNMessages: ExpressionMessages;
+type ExpressionMessagesListener = (messages: ExpressionMessages) => void;
 /**
  * Register (or replace) the message catalog for a locale key, making it selectable
  * via {@link configureExpressionMessages}. This is how a host adds a language the
@@ -663,6 +664,11 @@ declare function configureExpressionMessages({
  * The active {@link ExpressionMessages} catalog (English by default).
  */
 declare function getExpressionMessages(): ExpressionMessages;
+/**
+ * Subscribe to active message-catalog changes. Returns an idempotent unsubscribe
+ * function; listeners run synchronously after the new catalog becomes active.
+ */
+declare function subscribeExpressionMessages(listener: ExpressionMessagesListener): () => void;
 /**
  * One `{{ expression }}` hole located in a template document. `from` / `to` are
  * the character offsets of the inner expression itself — the text between the
@@ -729,4 +735,158 @@ declare function getTemplateDiagnosticsSync(source: string): ExpressionDiagnosti
  * Async {@link getTemplateDiagnosticsSync}, loading the engine on first use.
  */
 declare function getTemplateDiagnostics(source: string): Promise<ExpressionDiagnostic[]>;
-export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, MAX_CONDITION_TREE_DEPTH, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, emptyConditionGroup, enMessages, ensureConditionNodeIds, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, isZenRepresentableNumber, liftConditionTree, loadEngine, newConditionNodeId, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };
+/**
+ * The field-tree model behind the visual JSON Schema builder: a lossless projection of the
+ * JSON Schema subset the tree can host (`type` / `properties` / `items`, plus `required`).
+ * The schema JSON stays the single source of truth: {@link parseSchemaTree} REFUSES anything
+ * outside the subset (never a lossy rewrite), so a hand-written `oneOf` or `format` keeps its
+ * document JSON-only instead of silently vanishing on the first visual edit.
+ */
+/**
+ * The one dialect the tree round-trips: a document may omit `$schema` or declare exactly this.
+ */
+declare const SCHEMA_DIALECT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+type SchemaTreeFieldType = "any" | "array" | "boolean" | "integer" | "number" | "object" | "string";
+interface SchemaTreeField {
+  /**
+   * Stable row identity for React keys and targeted edits — a UI concern, never serialized.
+   */
+  id: string;
+  /**
+   * The property name under its parent object; unused on an array-element node.
+   */
+  name: string;
+  type: SchemaTreeFieldType;
+  /**
+   * Listed in the parent object's `required`; unused on an array-element node.
+   */
+  required: boolean;
+  /**
+   * The schema's `description` annotation; blank means none (not serialized).
+   */
+  description: string;
+  /**
+   * Sub-fields, meaningful when `type` is `object`.
+   */
+  children: SchemaTreeField[];
+  /**
+   * The element node, meaningful when `type` is `array`; `null` means untyped elements.
+   */
+  items: SchemaTreeField | null;
+  /**
+   * For an object or array node parsed from JSON, whether its source explicitly
+   * declared that type. `false` preserves a type-less applicator; omitted keeps the
+   * historical hand-built-tree default of emitting the type.
+   */
+  explicitType?: boolean;
+  /**
+   * Whether a blank / whitespace-only name came from a real `properties` key and must be
+   * persisted. Omitted blank names are unfinished UI rows and do not serialize.
+   */
+  preserveBlankName?: boolean;
+}
+interface SchemaTree {
+  fields: SchemaTreeField[];
+  /**
+   * Whether the source declared `$schema` (re-emitted verbatim on serialize).
+   */
+  dialect: boolean;
+  /**
+   * The root schema's `description` annotation, preserved verbatim across the round trip
+   * (the field view offers no root-level editor); blank means none.
+   */
+  description: string;
+  /**
+   * For a tree parsed from JSON, whether the root explicitly declared `type: "object"`.
+   * `false` preserves a type-less root; omitted keeps the historical hand-built-tree default
+   * of emitting the type.
+   */
+  explicitType?: boolean;
+}
+/**
+ * Why a document cannot be projected onto the field tree — structured so a UI can localize
+ * the explanation. Every code names the offending part where one exists.
+ */
+type SchemaTreeIssue = {
+  code: "invalid-description";
+} | {
+  code: "invalid-field-definition";
+  field: string;
+} | {
+  code: "invalid-field-type";
+  field: string;
+} | {
+  code: "invalid-json";
+} | {
+  code: "invalid-properties";
+} | {
+  code: "invalid-required";
+} | {
+  code: "misplaced-keyword";
+  keyword: string;
+  holder: "array" | "object";
+} | {
+  code: "root-not-object";
+} | {
+  code: "unknown-required-field";
+  field: string;
+} | {
+  code: "unsupported-dialect";
+} | {
+  code: "unsupported-field-type";
+  field: string;
+  type: string;
+} | {
+  code: "unsupported-keyword";
+  keyword: string;
+};
+type SchemaTreeParseResult = {
+  ok: true;
+  tree: SchemaTree;
+} | {
+  ok: false;
+  issue: SchemaTreeIssue;
+};
+/**
+ * A fresh {@link SchemaTreeField}, defaulting to an optional unnamed string field. The id is a
+ * tagged counter, not a UUID: field identity is a UI concern with no persistence or
+ * cross-process meaning — exactly the guarantee a React key needs.
+ */
+declare function newSchemaTreeField(overrides?: Partial<Omit<SchemaTreeField, "id">>): SchemaTreeField;
+/**
+ * The expression scope a schema tree declares: each named field becomes a typed variable, so a
+ * host can hand the result straight to `<ExpressionInput variables={…}>` (or `analyzeTypes`)
+ * and complete against the declared shape. Blank draft rows are skipped, while blank property
+ * names preserved by {@link parseSchemaTree} remain part of the scope.
+ */
+declare function schemaTreeToExpressionType(tree: SchemaTree): ExpressionType;
+/**
+ * Infer a draft 2020-12 JSON Schema from a sample payload — the "generate from example" path of
+ * the visual schema builder. Deliberately emits only the subset {@link parseSchemaTree} hosts
+ * (`type` / `properties` / `items`): integers stay `number` (a sample's `5` rarely promises
+ * integers forever) and nothing is marked `required` (validation strictness is an authoring
+ * decision, not something a single sample can attest).
+ */
+interface JsonObject {
+  [key: string]: Json;
+}
+type Json = null | boolean | number | string | Json[] | JsonObject;
+/**
+ * The schema a sample value attests: scalars map to their type, objects carry every observed
+ * property, arrays take the merged schema of their elements (an empty or mixed array leaves the
+ * items open). `null` says nothing about the real type, so it infers `{}` (any).
+ */
+declare function inferSchema(sample: Json): JsonObject;
+/**
+ * Project a schema document onto the field tree, or refuse with a structured
+ * {@link SchemaTreeIssue} when it uses anything beyond the subset. A blank document parses as
+ * an empty tree.
+ */
+declare function parseSchemaTree(text: string): SchemaTreeParseResult;
+/**
+ * The field tree back as pretty-printed schema JSON. A parsed type-less object root stays
+ * type-less; a hand-built tree still emits an object root by default. Clearing the contract
+ * entirely (an empty document) stays a source-mode action.
+ */
+declare function serializeSchemaTree(tree: SchemaTree): string;
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMessagesListener, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type Json, type LoadEngineOptions, MAX_CONDITION_TREE_DEPTH, SCHEMA_DIALECT_2020_12, type SchemaTree, type SchemaTreeField, type SchemaTreeFieldType, type SchemaTreeIssue, type SchemaTreeParseResult, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, emptyConditionGroup, enMessages, ensureConditionNodeIds, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, inferSchema, isEngineReady, isZenRepresentableNumber, liftConditionTree, loadEngine, newConditionNodeId, newSchemaTreeField, parseSchemaTree, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, schemaTreeToExpressionType, selectBranch, selectBranchWith, serializeSchemaTree, subscribeExpressionMessages, templateHoleAt, toZenLiteral, zhCNMessages };