@zvenigora/ng-eval-forms 0.1.0 → 0.2.0

package/fesm2022/zvenigora-ng-eval-forms.mjs

@@ -1,4 +1,4 @@
-import { createSignalContext } from '@zvenigora/ng-eval-signals';
+import { SignalContextWriteError, createSignalContext } from '@zvenigora/ng-eval-signals';
 
 /**
  * Coerces an expression's result to the boolean a `visible` rule needs.
@@ -46,6 +46,94 @@ const toVisible = (value) => !!value;
  */
 const toText = (value) => value === null || value === undefined ? '' : String(value);
 
+// A **value** import, and it has to stay one: `instanceof` needs the
+// constructor, not the type. `field-context.ts` already imports a value from
+// this package, so this adds no dependency edge.
+//
+// **The compiler enforces the form, and the plan said otherwise** - S 3.4 and
+// S 8.1 both call a type-only import here a change that "would compile and the
+// guard would silently never fire". Measured in step 3: `import type` is
+// **TS1361** at `applyErrorPolicy`'s `instanceof`, so it fails
+// `build:production` and gate 7, and under ts-jest's transpile path the elided
+// binding is a `ReferenceError` inside the `catch` that reddens *both* policy
+// arms. Loud at every gate, in other words - see the plan's revision 13.
+//
+// The failure mode that *is* silent is a different one and no import syntax
+// prevents it: two resolved copies of `@zvenigora/ng-eval-signals` give two
+// distinct constructors, and `instanceof` is then false for an error the other
+// copy threw. That is what the write-error arm of `evaluate-rule.spec.ts`
+// covers by throwing across the real package boundary rather than
+// constructing the error itself.
+/**
+ * Runs one rule under one {@link ExpressionErrorPolicy}, with the one error
+ * that must never be routed through it taken out first.
+ *
+ * ```ts
+ * applyErrorPolicy(() => evaluateRule(compiled, context, options), onError)
+ * ```
+ *
+ * **`SignalContextWriteError` re-throws in every mode, including a handler
+ * function** (plan S 3.4, 1.2.11). On `/reactive` that bypass came free -
+ * `createEvalSignal` re-throws it regardless of `onError` (`eval-signal.ts:353`)
+ * - and that behaviour lives *inside* `createEvalSignal`, which the `/signals`
+ * path never calls. It does not travel with the type, so it is re-implemented
+ * here or it does not exist. An assigning expression is illegal on every
+ * recompute with every dataset, so under this module's default of
+ * `'undefined'` it would otherwise render as a permanently blank field with
+ * nothing in the console.
+ *
+ * **The `instanceof` needs the constructor, so the import of that class is a
+ * *value* import** - see the note above it, and the plan's revision 13, for
+ * why that form is protected by the compiler rather than by this spec.
+ * `evaluate-rule.spec.ts`'s write-error arm asserts on the **class** rather
+ * than on a message because what it covers is the bypass's *behaviour* across
+ * a real package boundary, which no compiler check reaches.
+ *
+ * **It lives in the core while `/signals`' choke point does not, and the pair
+ * is not inconsistent** (S 3.4.1). The discriminator is what the symbol grants
+ * a caller who reaches it: `evaluateRule` published *is* a second path to the
+ * walk, which S 9.1 requires there be only one of, while this is a pure
+ * function over an error and a policy that takes no context, holds no compiled
+ * callback and cannot reach a walk. Publishing it grants a caller nothing they
+ * could not write in four lines, and buys the thing duplication would lose -
+ * one implementation of the write-error bypass for both adapters, which cannot
+ * then drift into disagreeing about the one error that must never be
+ * swallowed.
+ *
+ * **It re-throws the error it caught; `/reactive` re-wraps.** `createEvalSignal`
+ * throws a *new* `SignalContextWriteError` carrying the offending expression
+ * string, which it has and this path does not - a `LogicFn` holds a compiled
+ * callback, not the source text. So the same misuse surfaces a different
+ * object at each entry point: wrapped with the expression under `/reactive`,
+ * the original here. Stated rather than hidden; it is the one thing a consumer
+ * catching this error across both adapters would notice.
+ *
+ * @param run - The rule invocation. On `/signals` this is the choke point,
+ *              never a bare walk: containment is inside `run`, so a throw is
+ *              contained before this function decides what to do about it.
+ * @param policy - Defaults to `'undefined'`, per {@link ExpressionErrorPolicy}.
+ *                 Resolving the default *here* is what makes an absent policy
+ *                 mean `'undefined'` rather than inheriting `eval-signals`'
+ *                 opposite one.
+ */
+const applyErrorPolicy = (run, policy = 'undefined') => {
+    try {
+        return run();
+    }
+    catch (error) {
+        if (error instanceof SignalContextWriteError) {
+            throw error;
+        }
+        if (policy === 'throw') {
+            throw error;
+        }
+        if (policy === 'undefined') {
+            return undefined;
+        }
+        return policy(error);
+    }
+};
+
 /**
  * Composes one `EvalContext` for one field, out of two live sources.
  *
@@ -128,5 +216,5 @@ const createFieldContext = (formSource, fieldSource, options) => {
  * Generated bundle index. Do not edit.
  */
 
-export { createFieldContext, toText, toVisible };
+export { applyErrorPolicy, createFieldContext, toText, toVisible };
 //# sourceMappingURL=zvenigora-ng-eval-forms.mjs.map

package/fesm2022/zvenigora-ng-eval-forms.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"zvenigora-ng-eval-forms.mjs","sources":["../../../../modules/eval-forms/src/lib/coercion.ts","../../../../modules/eval-forms/src/lib/field-context.ts","../../../../modules/eval-forms/src/zvenigora-ng-eval-forms.ts"],"sourcesContent":["/**\r\n * Coerces an expression's result to the boolean a `visible` rule needs.\r\n *\r\n * **JavaScript truthiness, and nothing cleverer** (plan S 3.6). A rule author\r\n * writing `visible: \"country === 'US'\"` gets a boolean already; the coercion\r\n * exists for the ones who write `visible: \"country\"`.\r\n *\r\n * `undefined` is therefore the load-bearing input rather than an edge case.\r\n * An *empty* field and a *missing* field are indistinguishable here - S 3.4.3:\r\n * a field key bound to `undefined` is treated as absent, and an empty\r\n * `FormControl` is the common case - so both arrive as `undefined`, and both\r\n * mean \"not visible\".\r\n *\r\n * The string `'false'` is **visible**, because it is a non-empty string. That\r\n * is truthiness rather than parsing, and it is the answer a form-builder UI\r\n * storing every value as a string will hit. Documented in the README rather\r\n * than special-cased: a coercion that parsed `'false'` would then owe an\r\n * answer for `'no'`, `'0'` and `'off'`, none of which JavaScript has one for.\r\n *\r\n * Both adapters call this, which is why it is in the core: `/reactive` and\r\n * `/signals` differ in how they schedule the recompute and not in what the\r\n * result means (S 3.4.5).\r\n *\r\n * @param value - Whatever the expression evaluated to.\r\n * @returns `true` when the value is truthy.\r\n */\r\nexport const toVisible = (value: unknown): boolean => !!value;\r\n\r\n/**\r\n * Coerces an expression's result to the string a `text` rule needs.\r\n *\r\n * `String(value)`, with `null` and `undefined` mapping to `''` (plan S 3.6).\r\n * Those two are the carve-out and the only one: rendering the literal text\r\n * `undefined` into a label is the failure this rule exists to prevent, and it\r\n * is what a bare `String(value)` would do for the most ordinary input a form\r\n * has - the empty control of S 3.4.3.\r\n *\r\n * Every *other* falsy value stringifies normally: `0` is `'0'` and `false` is\r\n * `'false'`. Mapping all falsy values to `''` would be the obvious way to\r\n * write this rule wrongly, and it would blank a field whose value is\r\n * legitimately zero.\r\n *\r\n * @param value - Whatever the expression evaluated to.\r\n * @returns The value as a string, or `''` when it is `null` or `undefined`.\r\n */\r\nexport const toText = (value: unknown): string =>\r\n  value === null || value === undefined ? '' : String(value);\r\n","import { EvalContext, EvalOptions } from '@zvenigora/ng-eval-core';\r\nimport { SignalContextSource, createSignalContext } from '@zvenigora/ng-eval-signals';\r\n\r\n/**\r\n * Composes one `EvalContext` for one field, out of two live sources.\r\n *\r\n * The mechanism is **two lookups, not a joined record** (plan S 3.4.2). The\r\n * field half is a `createSignalContext` over `fieldSource`; the form half is a\r\n * second resolver pushed onto the same context's `lookups`. Both close over\r\n * their source and read it at resolve time, so a key added to either after\r\n * construction resolves - there is no third object to keep in sync, and no\r\n * write-through to N contexts.\r\n *\r\n * `EvalContext.get` walks `lookups` in order and takes the first\r\n * non-`undefined`, so the field half is consulted first.\r\n *\r\n * One context per field, never one shared across fields (plan S 3.4.1):\r\n * `get` resolves `scopes` and `original` *before* `lookups`, so anything left\r\n * on a shared context - an arrow function's leaked scope, say - would be read\r\n * ahead of every other field's source key of the same name, for the life of\r\n * the form.\r\n *\r\n * **Resolution is live; appearance is not reactive.** An expression that read\r\n * a then-missing key subscribed to nothing, so the owner of the source calls\r\n * `invalidate()` when the *key set* changes. A change to a *value* is\r\n * Angular's job and needs nothing.\r\n *\r\n * **Precedence is value-dependent, not permanent.** A field key wins while\r\n * its value is *present*: `EvalContext.get` treats `undefined` as absent at\r\n * every step, and the field resolver returns `undefined` both for \"no such\r\n * key\" and for \"key bound to `undefined`\" - so an empty `FormControl`, which\r\n * is the common case rather than an exotic one, falls through to the form\r\n * value. Documented as a limitation (plan S 3.4.3): distinguishing the two\r\n * would need a sentinel threaded through `EvalContext.get`, which is\r\n * `eval-core`'s and out of this phase's scope.\r\n *\r\n * @param formSource - The form-wide keys, shared by every field of the form.\r\n * @param fieldSource - The field-local keys. These win on a name collision,\r\n *                      while their value is not `undefined`.\r\n * @param options - Passed to `createSignalContext` for **both** halves;\r\n *                  configures this context and its resolvers, not the walk.\r\n *                  As upstream, `caseInsensitive` corrects identifier keys\r\n *                  here but not *property* names - the member visitor reads\r\n *                  those off the state's options, so the same options must\r\n *                  also reach `simpleEval` / `createState`.\r\n */\r\nexport const createFieldContext = (\r\n  formSource: SignalContextSource,\r\n  fieldSource: SignalContextSource,\r\n  options?: EvalOptions\r\n): EvalContext => {\r\n\r\n  const context = createSignalContext(fieldSource, options);\r\n\r\n  // The form half **borrows upstream's resolver rather than rewriting it**\r\n  // (S 3.4.2, candidate A, settled in step 2). The second context is\r\n  // discarded and only its closure survives, so this is still one\r\n  // `EvalContext` per field and the field half is still consulted first.\r\n  //\r\n  // The deciding reason is row 2 of S 3.4.2's measured table, and it is that\r\n  // the hand-written read is *wrong*, not merely thinner: it returns a signal\r\n  // un-called, so a form key holding `signal(undefined)` resolves to the\r\n  // signal **function**, which is truthy - and `visible: \"country\"` then\r\n  // renders a field precisely when its value is absent, silently, on an empty\r\n  // control. That is every form's first render. Recorded here because the\r\n  // alternative was rejected on correctness and stays rejected even once\r\n  // S 3.5 names a mechanism that keeps a plain-value record live.\r\n  //\r\n  // Borrowing also brings own-property semantics - so a server-supplied field\r\n  // named `constructor` cannot resolve off `Object.prototype` *through this\r\n  // half*, which is a narrower claim than it looks and no test reaches it:\r\n  // `get` consults `original` before `lookups`, and `getContextValue` reads a\r\n  // plain object as a bare property access, so an inherited name resolves\r\n  // there first and never arrives here (S 3.4.3's third layer, upstream and\r\n  // out of this phase's scope). It also brings `caseInsensitive` correction\r\n  // and `warnOnNestedSignals` over the form source, with no import beyond the\r\n  // one already here.\r\n  //\r\n  // The scan is the one cost: `createSignalContext` runs\r\n  // `warnOnNestedSignals` unconditionally, so a form of N fields scans the\r\n  // same form source N times and, in dev mode, would warn N times under\r\n  // *upstream's* symbol name for a call this library made. Construction-time\r\n  // only - no per-node or per-recompute path is touched.\r\n  context.lookups.push(...createSignalContext(formSource, options).lookups);\r\n\r\n  return context;\r\n};\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,SAAS,GAAG,CAAC,KAAc,KAAc,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;AAgBG;AACI,MAAM,MAAM,GAAG,CAAC,KAAc,KACnC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK;;AC3C3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CG;AACI,MAAM,kBAAkB,GAAG,CAChC,UAA+B,EAC/B,WAAgC,EAChC,OAAqB,KACN;IAEf,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BzD,IAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;AAEzE,IAAA,OAAO,OAAO;AAChB;;ACtFA;;AAEG;;;;"}
+{"version":3,"file":"zvenigora-ng-eval-forms.mjs","sources":["../../../../modules/eval-forms/src/lib/coercion.ts","../../../../modules/eval-forms/src/lib/error-policy.ts","../../../../modules/eval-forms/src/lib/field-context.ts","../../../../modules/eval-forms/src/zvenigora-ng-eval-forms.ts"],"sourcesContent":["/**\r\n * Coerces an expression's result to the boolean a `visible` rule needs.\r\n *\r\n * **JavaScript truthiness, and nothing cleverer** (plan S 3.6). A rule author\r\n * writing `visible: \"country === 'US'\"` gets a boolean already; the coercion\r\n * exists for the ones who write `visible: \"country\"`.\r\n *\r\n * `undefined` is therefore the load-bearing input rather than an edge case.\r\n * An *empty* field and a *missing* field are indistinguishable here - S 3.4.3:\r\n * a field key bound to `undefined` is treated as absent, and an empty\r\n * `FormControl` is the common case - so both arrive as `undefined`, and both\r\n * mean \"not visible\".\r\n *\r\n * The string `'false'` is **visible**, because it is a non-empty string. That\r\n * is truthiness rather than parsing, and it is the answer a form-builder UI\r\n * storing every value as a string will hit. Documented in the README rather\r\n * than special-cased: a coercion that parsed `'false'` would then owe an\r\n * answer for `'no'`, `'0'` and `'off'`, none of which JavaScript has one for.\r\n *\r\n * Both adapters call this, which is why it is in the core: `/reactive` and\r\n * `/signals` differ in how they schedule the recompute and not in what the\r\n * result means (S 3.4.5).\r\n *\r\n * @param value - Whatever the expression evaluated to.\r\n * @returns `true` when the value is truthy.\r\n */\r\nexport const toVisible = (value: unknown): boolean => !!value;\r\n\r\n/**\r\n * Coerces an expression's result to the string a `text` rule needs.\r\n *\r\n * `String(value)`, with `null` and `undefined` mapping to `''` (plan S 3.6).\r\n * Those two are the carve-out and the only one: rendering the literal text\r\n * `undefined` into a label is the failure this rule exists to prevent, and it\r\n * is what a bare `String(value)` would do for the most ordinary input a form\r\n * has - the empty control of S 3.4.3.\r\n *\r\n * Every *other* falsy value stringifies normally: `0` is `'0'` and `false` is\r\n * `'false'`. Mapping all falsy values to `''` would be the obvious way to\r\n * write this rule wrongly, and it would blank a field whose value is\r\n * legitimately zero.\r\n *\r\n * @param value - Whatever the expression evaluated to.\r\n * @returns The value as a string, or `''` when it is `null` or `undefined`.\r\n */\r\nexport const toText = (value: unknown): string =>\r\n  value === null || value === undefined ? '' : String(value);\r\n","// A **value** import, and it has to stay one: `instanceof` needs the\r\n// constructor, not the type. `field-context.ts` already imports a value from\r\n// this package, so this adds no dependency edge.\r\n//\r\n// **The compiler enforces the form, and the plan said otherwise** - S 3.4 and\r\n// S 8.1 both call a type-only import here a change that \"would compile and the\r\n// guard would silently never fire\". Measured in step 3: `import type` is\r\n// **TS1361** at `applyErrorPolicy`'s `instanceof`, so it fails\r\n// `build:production` and gate 7, and under ts-jest's transpile path the elided\r\n// binding is a `ReferenceError` inside the `catch` that reddens *both* policy\r\n// arms. Loud at every gate, in other words - see the plan's revision 13.\r\n//\r\n// The failure mode that *is* silent is a different one and no import syntax\r\n// prevents it: two resolved copies of `@zvenigora/ng-eval-signals` give two\r\n// distinct constructors, and `instanceof` is then false for an error the other\r\n// copy threw. That is what the write-error arm of `evaluate-rule.spec.ts`\r\n// covers by throwing across the real package boundary rather than\r\n// constructing the error itself.\r\nimport { SignalContextWriteError } from '@zvenigora/ng-eval-signals';\r\n\r\n/**\r\n * What a field property does when its expression throws at runtime.\r\n *\r\n * - `'throw'` - rethrow, matching `eval-signals`' own default.\r\n * - `'undefined'` - the property resolves `undefined`, which `toVisible`\r\n *   reads as not visible and `toText` reads as `''`.\r\n * - a function - called with the error; its return value becomes the\r\n *   property's value.\r\n *\r\n * **The default here is `'undefined'`, the opposite of `eval-signals`'**, and\r\n * the consumer is the reason (plan S 3.4.4). An expression that fails in\r\n * `eval-signals` was written by the developer reading the stack trace. An\r\n * expression that fails here may have been typed into a form builder by an\r\n * end user, and the right response to \"the admin wrote a bad rule\" is a field\r\n * that does not render, not an application that throws on every change\r\n * detection pass. Consumers who want the strict behaviour pass `'throw'`.\r\n *\r\n * Resolving that default is a real step and not a formality: `createEvalSignal`\r\n * does `options?.onError ?? 'throw'`, so forwarding an *absent* policy verbatim\r\n * inherits `'throw'` - the opposite of this default. The `/reactive` binding\r\n * substitutes its own before the call.\r\n *\r\n * The union is structurally identical to `EvalSignalOptions['onError']`\r\n * **deliberately**: `/reactive` resolves the default here and forwards the\r\n * value to `createEvalSignal` with no mapping between the two unions, which is\r\n * where two near-identical types would drift apart.\r\n *\r\n * `SignalContextWriteError` is **not** routed through this, in either adapter,\r\n * matching `phase-3-plan.md` S 3.6.3. A write violation is static - illegal on\r\n * every recompute with every dataset - and swallowing it under a default of\r\n * `'undefined'` would hand every consumer a silent blank for a bug in the\r\n * rule's own syntax. `createEvalSignal` already bypasses `onError` for it.\r\n *\r\n * **{@link applyErrorPolicy} ships beside this type as of Phase 6** (its\r\n * S 3.4). Through Phase 4 only the type shipped, because the helper would have\r\n * had no caller: on the `/reactive` path - the only path Phase 4 shipped -\r\n * `createEvalSignal` applies the three cases internally, and shipping an\r\n * unexercised code path is what S 9.1 declined to do for the scope-leak\r\n * containment. The `/signals` adapter is that caller **from step 4**, where\r\n * the registrars stop being stubs; `/reactive` does not use the helper at all.\r\n */\r\nexport type ExpressionErrorPolicy =\r\n  | 'throw'\r\n  | 'undefined'\r\n  | ((error: unknown) => unknown);\r\n\r\n/**\r\n * Runs one rule under one {@link ExpressionErrorPolicy}, with the one error\r\n * that must never be routed through it taken out first.\r\n *\r\n * ```ts\r\n * applyErrorPolicy(() => evaluateRule(compiled, context, options), onError)\r\n * ```\r\n *\r\n * **`SignalContextWriteError` re-throws in every mode, including a handler\r\n * function** (plan S 3.4, 1.2.11). On `/reactive` that bypass came free -\r\n * `createEvalSignal` re-throws it regardless of `onError` (`eval-signal.ts:353`)\r\n * - and that behaviour lives *inside* `createEvalSignal`, which the `/signals`\r\n * path never calls. It does not travel with the type, so it is re-implemented\r\n * here or it does not exist. An assigning expression is illegal on every\r\n * recompute with every dataset, so under this module's default of\r\n * `'undefined'` it would otherwise render as a permanently blank field with\r\n * nothing in the console.\r\n *\r\n * **The `instanceof` needs the constructor, so the import of that class is a\r\n * *value* import** - see the note above it, and the plan's revision 13, for\r\n * why that form is protected by the compiler rather than by this spec.\r\n * `evaluate-rule.spec.ts`'s write-error arm asserts on the **class** rather\r\n * than on a message because what it covers is the bypass's *behaviour* across\r\n * a real package boundary, which no compiler check reaches.\r\n *\r\n * **It lives in the core while `/signals`' choke point does not, and the pair\r\n * is not inconsistent** (S 3.4.1). The discriminator is what the symbol grants\r\n * a caller who reaches it: `evaluateRule` published *is* a second path to the\r\n * walk, which S 9.1 requires there be only one of, while this is a pure\r\n * function over an error and a policy that takes no context, holds no compiled\r\n * callback and cannot reach a walk. Publishing it grants a caller nothing they\r\n * could not write in four lines, and buys the thing duplication would lose -\r\n * one implementation of the write-error bypass for both adapters, which cannot\r\n * then drift into disagreeing about the one error that must never be\r\n * swallowed.\r\n *\r\n * **It re-throws the error it caught; `/reactive` re-wraps.** `createEvalSignal`\r\n * throws a *new* `SignalContextWriteError` carrying the offending expression\r\n * string, which it has and this path does not - a `LogicFn` holds a compiled\r\n * callback, not the source text. So the same misuse surfaces a different\r\n * object at each entry point: wrapped with the expression under `/reactive`,\r\n * the original here. Stated rather than hidden; it is the one thing a consumer\r\n * catching this error across both adapters would notice.\r\n *\r\n * @param run - The rule invocation. On `/signals` this is the choke point,\r\n *              never a bare walk: containment is inside `run`, so a throw is\r\n *              contained before this function decides what to do about it.\r\n * @param policy - Defaults to `'undefined'`, per {@link ExpressionErrorPolicy}.\r\n *                 Resolving the default *here* is what makes an absent policy\r\n *                 mean `'undefined'` rather than inheriting `eval-signals`'\r\n *                 opposite one.\r\n */\r\nexport const applyErrorPolicy = <T>(\r\n  run: () => T,\r\n  policy: ExpressionErrorPolicy = 'undefined'\r\n): T | undefined => {\r\n\r\n  try {\r\n    return run();\r\n  } catch (error) {\r\n    if (error instanceof SignalContextWriteError) {\r\n      throw error;\r\n    }\r\n\r\n    if (policy === 'throw') {\r\n      throw error;\r\n    }\r\n\r\n    if (policy === 'undefined') {\r\n      return undefined;\r\n    }\r\n\r\n    return policy(error) as T | undefined;\r\n  }\r\n};\r\n","import { EvalContext, EvalOptions } from '@zvenigora/ng-eval-core';\r\nimport { SignalContextSource, createSignalContext } from '@zvenigora/ng-eval-signals';\r\n\r\n/**\r\n * Composes one `EvalContext` for one field, out of two live sources.\r\n *\r\n * The mechanism is **two lookups, not a joined record** (plan S 3.4.2). The\r\n * field half is a `createSignalContext` over `fieldSource`; the form half is a\r\n * second resolver pushed onto the same context's `lookups`. Both close over\r\n * their source and read it at resolve time, so a key added to either after\r\n * construction resolves - there is no third object to keep in sync, and no\r\n * write-through to N contexts.\r\n *\r\n * `EvalContext.get` walks `lookups` in order and takes the first\r\n * non-`undefined`, so the field half is consulted first.\r\n *\r\n * One context per field, never one shared across fields (plan S 3.4.1):\r\n * `get` resolves `scopes` and `original` *before* `lookups`, so anything left\r\n * on a shared context - an arrow function's leaked scope, say - would be read\r\n * ahead of every other field's source key of the same name, for the life of\r\n * the form.\r\n *\r\n * **Resolution is live; appearance is not reactive.** An expression that read\r\n * a then-missing key subscribed to nothing, so the owner of the source calls\r\n * `invalidate()` when the *key set* changes. A change to a *value* is\r\n * Angular's job and needs nothing.\r\n *\r\n * **Precedence is value-dependent, not permanent.** A field key wins while\r\n * its value is *present*: `EvalContext.get` treats `undefined` as absent at\r\n * every step, and the field resolver returns `undefined` both for \"no such\r\n * key\" and for \"key bound to `undefined`\" - so an empty `FormControl`, which\r\n * is the common case rather than an exotic one, falls through to the form\r\n * value. Documented as a limitation (plan S 3.4.3): distinguishing the two\r\n * would need a sentinel threaded through `EvalContext.get`, which is\r\n * `eval-core`'s and out of this phase's scope.\r\n *\r\n * @param formSource - The form-wide keys, shared by every field of the form.\r\n * @param fieldSource - The field-local keys. These win on a name collision,\r\n *                      while their value is not `undefined`.\r\n * @param options - Passed to `createSignalContext` for **both** halves;\r\n *                  configures this context and its resolvers, not the walk.\r\n *                  As upstream, `caseInsensitive` corrects identifier keys\r\n *                  here but not *property* names - the member visitor reads\r\n *                  those off the state's options, so the same options must\r\n *                  also reach `simpleEval` / `createState`.\r\n */\r\nexport const createFieldContext = (\r\n  formSource: SignalContextSource,\r\n  fieldSource: SignalContextSource,\r\n  options?: EvalOptions\r\n): EvalContext => {\r\n\r\n  const context = createSignalContext(fieldSource, options);\r\n\r\n  // The form half **borrows upstream's resolver rather than rewriting it**\r\n  // (S 3.4.2, candidate A, settled in step 2). The second context is\r\n  // discarded and only its closure survives, so this is still one\r\n  // `EvalContext` per field and the field half is still consulted first.\r\n  //\r\n  // The deciding reason is row 2 of S 3.4.2's measured table, and it is that\r\n  // the hand-written read is *wrong*, not merely thinner: it returns a signal\r\n  // un-called, so a form key holding `signal(undefined)` resolves to the\r\n  // signal **function**, which is truthy - and `visible: \"country\"` then\r\n  // renders a field precisely when its value is absent, silently, on an empty\r\n  // control. That is every form's first render. Recorded here because the\r\n  // alternative was rejected on correctness and stays rejected even once\r\n  // S 3.5 names a mechanism that keeps a plain-value record live.\r\n  //\r\n  // Borrowing also brings own-property semantics - so a server-supplied field\r\n  // named `constructor` cannot resolve off `Object.prototype` *through this\r\n  // half*, which is a narrower claim than it looks and no test reaches it:\r\n  // `get` consults `original` before `lookups`, and `getContextValue` reads a\r\n  // plain object as a bare property access, so an inherited name resolves\r\n  // there first and never arrives here (S 3.4.3's third layer, upstream and\r\n  // out of this phase's scope). It also brings `caseInsensitive` correction\r\n  // and `warnOnNestedSignals` over the form source, with no import beyond the\r\n  // one already here.\r\n  //\r\n  // The scan is the one cost: `createSignalContext` runs\r\n  // `warnOnNestedSignals` unconditionally, so a form of N fields scans the\r\n  // same form source N times and, in dev mode, would warn N times under\r\n  // *upstream's* symbol name for a call this library made. Construction-time\r\n  // only - no per-node or per-recompute path is touched.\r\n  context.lookups.push(...createSignalContext(formSource, options).lookups);\r\n\r\n  return context;\r\n};\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,SAAS,GAAG,CAAC,KAAc,KAAc,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;AAgBG;AACI,MAAM,MAAM,GAAG,CAAC,KAAc,KACnC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK;;AC9C3D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAiDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDG;AACI,MAAM,gBAAgB,GAAG,CAC9B,GAAY,EACZ,MAAA,GAAgC,WAAW,KAC1B;AAEjB,IAAA,IAAI;QACF,OAAO,GAAG,EAAE;IACd;IAAE,OAAO,KAAK,EAAE;AACd,QAAA,IAAI,KAAK,YAAY,uBAAuB,EAAE;AAC5C,YAAA,MAAM,KAAK;QACb;AAEA,QAAA,IAAI,MAAM,KAAK,OAAO,EAAE;AACtB,YAAA,MAAM,KAAK;QACb;AAEA,QAAA,IAAI,MAAM,KAAK,WAAW,EAAE;AAC1B,YAAA,OAAO,SAAS;QAClB;AAEA,QAAA,OAAO,MAAM,CAAC,KAAK,CAAkB;IACvC;AACF;;ACzIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CG;AACI,MAAM,kBAAkB,GAAG,CAChC,UAA+B,EAC/B,WAAgC,EAChC,OAAqB,KACN;IAEf,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BzD,IAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;AAEzE,IAAA,OAAO,OAAO;AAChB;;ACtFA;;AAEG;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvenigora/ng-eval-forms",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Angular form field properties from ng-eval expressions",
   "repository": {
     "type": "git",
@@ -18,9 +18,13 @@
     "@angular/core": ">=19.0.0",
     "@angular/forms": ">=19.0.0",
     "rxjs": "^7.8.0",
+    "acorn-walk": "^8.3.0",
     "@zvenigora/ng-eval-core": "^0.3.0",
     "@zvenigora/ng-eval-signals": "^0.1.0"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "sideEffects": false,
   "module": "fesm2022/zvenigora-ng-eval-forms.mjs",
   "typings": "types/zvenigora-ng-eval-forms.d.ts",
@@ -35,6 +39,10 @@
     "./reactive": {
       "types": "./types/zvenigora-ng-eval-forms-reactive.d.ts",
       "default": "./fesm2022/zvenigora-ng-eval-forms-reactive.mjs"
+    },
+    "./signals": {
+      "types": "./types/zvenigora-ng-eval-forms-signals.d.ts",
+      "default": "./fesm2022/zvenigora-ng-eval-forms-signals.mjs"
     }
   },
   "type": "module",

package/types/zvenigora-ng-eval-forms-signals.d.ts

@@ -0,0 +1,135 @@
+import * as _angular_core from '@angular/core';
+import { WritableSignal } from '@angular/core';
+import * as _angular_forms_signals from '@angular/forms/signals';
+import { PathKind, SchemaPath, SchemaPathRules } from '@angular/forms/signals';
+import { EvalOptions } from '@zvenigora/ng-eval-core';
+import { ExpressionErrorPolicy } from '@zvenigora/ng-eval-forms';
+
+/**
+ * What `createExpressionRules` takes, and what a single registration may
+ * override (plan S 5).
+ */
+interface ExpressionRuleOptions {
+    /**
+     * Passed to the context and to the walk. `caseInsensitive` has to reach
+     * both: on the context it corrects identifier keys, and on the walk it
+     * corrects *property* names, which the member visitor reads off the
+     * state's options.
+     *
+     * **A per-registration value reaches exactly one of the three places it
+     * has to: the walk** (plan S 3.5.3). The other two read the **factory's**
+     * options, which are fixed when `createExpressionRules` is called: the memo
+     * is built once, there; the context is minted per registration by
+     * `createRuleContext()` but always from that same fixed setting, so a
+     * registration cannot move it. So overriding this per registration corrects
+     * *property* names and leaves *identifier* keys on the factory's setting,
+     * and one expression then obeys two casing rules. Set `caseInsensitive` on
+     * the **factory** unless that is the behaviour you want.
+     *
+     * Revision 19 item 2 corrects "both are made once, at
+     * `createExpressionRules` time", which was wrong about the context and is
+     * the claim the README states correctly.
+     */
+    eval?: EvalOptions;
+    /**
+     * What a field property does when its expression throws at runtime.
+     * Defaults to `'undefined'` here, the opposite of `eval-signals`' own
+     * default - see `ExpressionErrorPolicy` for why.
+     */
+    onError?: ExpressionErrorPolicy;
+}
+/**
+ * The three registrars one factory returns, one per Angular rule.
+ *
+ * **One call per Angular primitive, never an aggregate** (plan S 3.5.1). A
+ * single `evalRules(p.x, { visible, text, disabled })` would register three
+ * different Angular rules behind one name, hiding which one each property
+ * maps to - which is the `/signals` reviewer checklist's item 4 expressed as
+ * an API.
+ *
+ * Named after the **property**, not after Angular's rule: `evalVisible`
+ * registers `hidden`, inverted once inside the registrar rather than in every
+ * consumer's expression, so the same expression string means the same thing
+ * at this entry point and at `/reactive`.
+ */
+interface ExpressionRules {
+    /** Registers Angular's `hidden`, inverted (plan S 3.5.1). */
+    evalVisible: <TValue, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, expression: string, options?: ExpressionRuleOptions) => void;
+    /** Registers `metadata(path, TEXT, …)` (plan S 1.2.8, S 3.5). */
+    evalText: <TValue, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, expression: string, options?: ExpressionRuleOptions) => void;
+    /**
+     * Registers Angular's `disabled`.
+     *
+     * The `reason` is authored as a static string and is never
+     * expression-derived (plan S 3.5.2). Angular's `when` returns
+     * `boolean | string` and a truthy string is *both* "disabled" and "the
+     * reason", so a rule yielding `'false'` would otherwise disable the field
+     * with the reason `"false"` - the `toVisible` truthiness trap in a new
+     * shape. Keeping the expression boolean and the reason static is what kills
+     * it.
+     */
+    evalDisabled: <TValue, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, expression: string, options?: ExpressionRuleOptions & {
+        reason?: string;
+    }) => void;
+}
+/**
+ * Binds one model signal and returns the three expression-driven registrars.
+ *
+ * **A factory rather than free functions, because a `LogicFn` cannot recover
+ * the source** (plan S 3.2.1). `RootFieldContext` exposes the *current*
+ * field's node plus compile-time-token accessors and no root or parent
+ * handle, so a rule on `p.city` evaluating `country === "US"` has no route to
+ * `country` from inside the `LogicFn`. The source must be closed over at
+ * registration or it is unreachable.
+ *
+ * ```ts
+ * const rules = createExpressionRules(model);
+ * const s = schema<Model>((p) => {
+ *   required(p.email);                                 // Angular's
+ *   rules.evalVisible(p.city, 'country === "US"');     // ours
+ * });
+ * const f = form(model, s);
+ * ```
+ *
+ * **A schema *value* shared across models is the unsupported shape.** Nothing
+ * stops two `form()` calls from one schema - Angular re-invokes the schema
+ * body once per `form()`, so each form mints its own contexts - but the
+ * registrars close over the **factory's** model, and the factory is bound to
+ * one. A schema built from `createExpressionRules(modelA)` and reused for
+ * `form(modelB, s)` re-registers every rule and every one of them still reads
+ * model A: form B renders against form A's data, silently, with no error and
+ * a fully functional form (Q9).
+ *
+ * The supported reuse shape is therefore a schema **function of the rules** -
+ * `const makeSchema = (rules) => schema<Model>(p => …)`, called per form -
+ * which keeps reuse while giving each form a factory bound to its own model.
+ *
+ * What one factory retains: **one private memo**, per factory, bounded by the
+ * union of keys the rules mention; and, per rule per `form()`, one
+ * `EvalContext` and one compiled callback. Nothing registers with a
+ * `DestroyRef` and there is no `destroy()` - it all becomes garbage with the
+ * form (S 3.6).
+ */
+declare const createExpressionRules: <TModel extends object>(model: WritableSignal<TModel>, options?: ExpressionRuleOptions) => ExpressionRules;
+
+/**
+ * The metadata key `evalText` writes through and a consumer reads back
+ * (plan S 1.2.8, S 3.5).
+ *
+ * `text` has no dedicated primitive in `@angular/forms/signals` the way
+ * `hidden` and `disabled` do, so it is `metadata(path, TEXT, logic)` against a
+ * key created once - which is Angular's own mechanism rather than a second one
+ * beside it, per the `/signals` reviewer checklist's item 4.
+ *
+ * **Created once, at module scope, deliberately.** `createMetadataKey` mints a
+ * fresh key per call, and the write and the read-back have to name the same
+ * object: a key re-created per access would let `metadata(p.x, TEXT, …)` write
+ * under one identity and `f.x().metadata(TEXT)` read under another, and the
+ * read would be `undefined` with nothing to show why. `text-key.spec.ts`
+ * asserts the two halves of that - `createMetadataKey` is per-call, and this
+ * is one of its results rather than the function itself.
+ */
+declare const TEXT: _angular_forms_signals.MetadataKey<_angular_core.Signal<string | undefined>, string, string | undefined>;
+
+export { TEXT, createExpressionRules };
+export type { ExpressionRuleOptions, ExpressionRules };

package/types/zvenigora-ng-eval-forms.d.ts

@@ -80,15 +80,68 @@ declare const toText: (value: unknown) => string;
  * `'undefined'` would hand every consumer a silent blank for a bug in the
  * rule's own syntax. `createEvalSignal` already bypasses `onError` for it.
  *
- * **Only the type ships in this phase.** A matching `applyErrorPolicy` helper
- * would have no caller: on the `/reactive` path - the only path Phase 4 ships
- * - `createEvalSignal` applies the three cases internally. Its sole consumer
- * is the `/signals` adapter, which is on paper only (S 9), so the helper is
- * deferred to that phase and will be written against this type. Shipping an
- * unexercised code path is what S 9.1 declines to do for the scope-leak
- * containment, and the rule applies to both or to neither.
+ * **{@link applyErrorPolicy} ships beside this type as of Phase 6** (its
+ * S 3.4). Through Phase 4 only the type shipped, because the helper would have
+ * had no caller: on the `/reactive` path - the only path Phase 4 shipped -
+ * `createEvalSignal` applies the three cases internally, and shipping an
+ * unexercised code path is what S 9.1 declined to do for the scope-leak
+ * containment. The `/signals` adapter is that caller **from step 4**, where
+ * the registrars stop being stubs; `/reactive` does not use the helper at all.
  */
 type ExpressionErrorPolicy = 'throw' | 'undefined' | ((error: unknown) => unknown);
+/**
+ * Runs one rule under one {@link ExpressionErrorPolicy}, with the one error
+ * that must never be routed through it taken out first.
+ *
+ * ```ts
+ * applyErrorPolicy(() => evaluateRule(compiled, context, options), onError)
+ * ```
+ *
+ * **`SignalContextWriteError` re-throws in every mode, including a handler
+ * function** (plan S 3.4, 1.2.11). On `/reactive` that bypass came free -
+ * `createEvalSignal` re-throws it regardless of `onError` (`eval-signal.ts:353`)
+ * - and that behaviour lives *inside* `createEvalSignal`, which the `/signals`
+ * path never calls. It does not travel with the type, so it is re-implemented
+ * here or it does not exist. An assigning expression is illegal on every
+ * recompute with every dataset, so under this module's default of
+ * `'undefined'` it would otherwise render as a permanently blank field with
+ * nothing in the console.
+ *
+ * **The `instanceof` needs the constructor, so the import of that class is a
+ * *value* import** - see the note above it, and the plan's revision 13, for
+ * why that form is protected by the compiler rather than by this spec.
+ * `evaluate-rule.spec.ts`'s write-error arm asserts on the **class** rather
+ * than on a message because what it covers is the bypass's *behaviour* across
+ * a real package boundary, which no compiler check reaches.
+ *
+ * **It lives in the core while `/signals`' choke point does not, and the pair
+ * is not inconsistent** (S 3.4.1). The discriminator is what the symbol grants
+ * a caller who reaches it: `evaluateRule` published *is* a second path to the
+ * walk, which S 9.1 requires there be only one of, while this is a pure
+ * function over an error and a policy that takes no context, holds no compiled
+ * callback and cannot reach a walk. Publishing it grants a caller nothing they
+ * could not write in four lines, and buys the thing duplication would lose -
+ * one implementation of the write-error bypass for both adapters, which cannot
+ * then drift into disagreeing about the one error that must never be
+ * swallowed.
+ *
+ * **It re-throws the error it caught; `/reactive` re-wraps.** `createEvalSignal`
+ * throws a *new* `SignalContextWriteError` carrying the offending expression
+ * string, which it has and this path does not - a `LogicFn` holds a compiled
+ * callback, not the source text. So the same misuse surfaces a different
+ * object at each entry point: wrapped with the expression under `/reactive`,
+ * the original here. Stated rather than hidden; it is the one thing a consumer
+ * catching this error across both adapters would notice.
+ *
+ * @param run - The rule invocation. On `/signals` this is the choke point,
+ *              never a bare walk: containment is inside `run`, so a throw is
+ *              contained before this function decides what to do about it.
+ * @param policy - Defaults to `'undefined'`, per {@link ExpressionErrorPolicy}.
+ *                 Resolving the default *here* is what makes an absent policy
+ *                 mean `'undefined'` rather than inheriting `eval-signals`'
+ *                 opposite one.
+ */
+declare const applyErrorPolicy: <T>(run: () => T, policy?: ExpressionErrorPolicy) => T | undefined;
 
 /**
  * Composes one `EvalContext` for one field, out of two live sources.
@@ -135,5 +188,5 @@ type ExpressionErrorPolicy = 'throw' | 'undefined' | ((error: unknown) => unknow
  */
 declare const createFieldContext: (formSource: SignalContextSource, fieldSource: SignalContextSource, options?: EvalOptions) => EvalContext;
 
-export { createFieldContext, toText, toVisible };
+export { applyErrorPolicy, createFieldContext, toText, toVisible };
 export type { ExpressionErrorPolicy };