@camstack/types 1.1.20 → 1.1.22

package/dist/expression/link-expression.d.ts

@@ -0,0 +1,44 @@
+import { type ExpressionEvalOptions } from './evaluator.js';
+import type { ExpressionValue } from './ast.js';
+/** The `now` epoch-ms binding is auto-injected into every evaluation and is a
+ *  reserved binding name (authors may not rebind it). */
+export declare const EXPRESSION_INJECTED_NOW = "now";
+/**
+ * Coerce an untrusted `getByPath` / mirror read to an `ExpressionValue`.
+ * Non-primitive values (objects, arrays, `undefined`, functions, bigint,
+ * symbol) and non-finite numbers become `undefined` so the caller can apply
+ * its binding-miss policy (→ `null`). `null` itself is a valid value.
+ */
+export declare function toExpressionValue(raw: unknown): ExpressionValue | undefined;
+/** Shape the author-time validator accepts (structural subset of a
+ *  `DeviceLinkExpressionSource`). */
+export interface ExpressionSourceInput {
+    readonly expr: string;
+    readonly bindings: Readonly<Record<string, unknown>>;
+}
+/**
+ * Author-time validation. Returns `null` when the source is valid, else a
+ * human-readable error message. Checks: the expression compiles; binding count
+ * is within `MAX_EXPRESSION_BINDINGS`; every binding name is a legal identifier,
+ * is not reserved (`now`/keywords) and does not shadow a builtin; and every
+ * FREE identifier of the AST is covered by a binding or the injected `now`.
+ */
+export declare function validateExpressionSource(src: ExpressionSourceInput): string | null;
+/** Result of a link-expression evaluation — `ok` carries the value, the error
+ *  branch carries a reason the async channel can log while the sync channel
+ *  silently skips. */
+export type EvaluateLinkExpressionResult = {
+    readonly ok: true;
+    readonly value: ExpressionValue;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Shared read-path evaluation for BOTH resolver channels. Builds a null-proto
+ * scope from `bindingValues` plus the injected `now` (supplied by the caller
+ * for determinism/testability), compiles via the LRU, and evaluates. Any
+ * failure (parse or eval) returns `{ ok: false }` — the caller treats that as
+ * "skip this link".
+ */
+export declare function evaluateLinkExpression(expr: string, bindingValues: Readonly<Record<string, ExpressionValue>>, now: number, opts?: ExpressionEvalOptions): EvaluateLinkExpressionResult;

package/dist/expression/parser.d.ts

@@ -0,0 +1,12 @@
+import type { ExpressionNode } from './ast.js';
+export interface ParsedExpression {
+    readonly ast: ExpressionNode;
+    /** Free identifiers referenced by the expression (NOT callees). */
+    readonly identifiers: ReadonlySet<string>;
+    /** Builtin function names called by the expression. */
+    readonly callees: ReadonlySet<string>;
+    readonly nodeCount: number;
+}
+/** Tokenize + parse `source` into a validated `ParsedExpression`. Throws
+ *  `ExpressionParseError` on any lexical or grammatical failure. */
+export declare function parseExpression(source: string): ParsedExpression;

package/dist/expression/tokenizer.d.ts

@@ -0,0 +1,38 @@
+/** The fixed punctuator set of the language. */
+export type Punctuator = '(' | ')' | ',' | '?' | ':' | '+' | '-' | '*' | '/' | '%' | '!' | '<' | '<=' | '>' | '>=' | '==' | '!=' | '&&' | '||';
+/** The three value keywords. */
+export type Keyword = 'true' | 'false' | 'null';
+export interface NumberToken {
+    readonly type: 'number';
+    readonly value: number;
+    readonly pos: number;
+}
+export interface StringToken {
+    readonly type: 'string';
+    readonly value: string;
+    readonly pos: number;
+}
+export interface IdentifierToken {
+    readonly type: 'identifier';
+    readonly name: string;
+    readonly pos: number;
+}
+export interface KeywordToken {
+    readonly type: 'keyword';
+    readonly keyword: Keyword;
+    readonly pos: number;
+}
+export interface PunctToken {
+    readonly type: 'punct';
+    readonly punct: Punctuator;
+    readonly pos: number;
+}
+export interface EofToken {
+    readonly type: 'eof';
+    readonly pos: number;
+}
+export type Token = NumberToken | StringToken | IdentifierToken | KeywordToken | PunctToken | EofToken;
+/** Tokenize `source` into a flat token list ending with a single `eof` token.
+ *  Throws `ExpressionParseError` on any illegal character or unterminated
+ *  string. */
+export declare function tokenize(source: string): readonly Token[];