@camstack/types 1.1.19 → 1.1.21

package/dist/device/device-management.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
-import type { DeviceType } from './device-type.js';
 import type { IDevice } from './device.js';
+import type { DeviceType } from './device-type.js';
 import type { SourceInfo } from './source-info.js';
 export interface DeviceManualCreation {
     getChildCreationSchema(type: DeviceType): z.ZodObject<z.core.$ZodLooseShape>;
@@ -95,17 +95,54 @@ export interface ChildLayoutEntry {
     readonly collapsed?: boolean;
 }
 export type ChildLayout = readonly ChildLayoutEntry[];
-/** One end of a device link: a single field on a source device's capability,
- *  addressed by the source's re-sync-stable accessory `stableIdSuffix`
+/** Field source: copy one field of a sibling accessory's cap status.
+ *  Addressed by the source's re-sync-stable accessory `stableIdSuffix`
  *  (`sourceKey`) — NOT a raw numeric id — so the link survives a re-sync. The
  *  source must be a sibling accessory under the SAME parent container as the
- *  target device; resolution is `${parentStableId}-${sourceKey}` (cross-parent
- *  links are out of scope and resolve to no source). */
-export interface DeviceLinkSource {
+ *  target device; resolution is `${parentStableId}-${sourceKey}`. For a source
+ *  anywhere else in the cluster use `DeviceLinkGlobalSource`. */
+export interface DeviceLinkFieldSource {
+    readonly kind?: 'field';
     readonly sourceKey: string;
     readonly cap: string;
     readonly fieldPath: string;
 }
+/** Literal source: a per-device constant (e.g. `battery.binary = true`,
+ *  a consumable item's `label`/`resettable`). No sibling is read. */
+export interface DeviceLinkLiteralSource {
+    readonly kind: 'literal';
+    readonly value: string | number | boolean | null;
+}
+/** Global source (P2e): copy one field of ANY device's cap status, regardless
+ *  of parent container. Addressed by the source device's FULL `stableId` —
+ *  chosen over the numeric id because a re-sync (`resetToSource`) REALLOCATES
+ *  numeric ids while stableIds are deterministic from the provider (the same
+ *  property the sibling `sourceKey` mechanism relies on). stableId uniqueness
+ *  is formally per-addon; the resolver matches the first meta row with that
+ *  stableId (effective global uniqueness — an `addonId` disambiguator can be
+ *  added later without a wire break). */
+export interface DeviceLinkGlobalSource {
+    readonly kind: 'global';
+    readonly sourceStableId: string;
+    readonly cap: string;
+    readonly fieldPath: string;
+}
+/** The source kinds a single expression BINDING may use — a sibling FIELD, a
+ *  per-device LITERAL, or a GLOBAL device field. Never another expression:
+ *  bindings do not nest, so an expression cannot reference another expression. */
+export type DeviceLinkExpressionBinding = DeviceLinkFieldSource | DeviceLinkLiteralSource | DeviceLinkGlobalSource;
+/** Expression source (Stage X): compute the target field from N named source
+ *  bindings via a safe, non-Turing-complete infix expression (see
+ *  `packages/types/src/expression/`). Each binding resolves to an
+ *  `ExpressionValue` and is exposed to the expression under its record key.
+ *  `now` (epoch ms) is auto-injected and is a reserved binding name. The
+ *  evaluated result flows through `transform` exactly like a scalar source. */
+export interface DeviceLinkExpressionSource {
+    readonly kind: 'expression';
+    readonly expr: string;
+    readonly bindings: Readonly<Record<string, DeviceLinkExpressionBinding>>;
+}
+export type DeviceLinkSource = DeviceLinkFieldSource | DeviceLinkLiteralSource | DeviceLinkGlobalSource | DeviceLinkExpressionSource;
 /** The target field a link writes: a dot-path into the target cap's status. */
 export interface DeviceLinkTarget {
     readonly cap: string;
@@ -134,6 +171,42 @@ export interface DeviceLink {
     readonly transform?: DeviceLinkTransform;
 }
 export type DeviceLinks = readonly DeviceLink[];
+/** Per-cap display refinement inside a `DeviceDisplayOverride` — unit/precision
+ *  only (icon/label/hidden are device-level). Keyed by cap name for devices
+ *  carrying several numeric caps (e.g. power-meter). */
+export interface DeviceCapDisplayOverride {
+    readonly unit?: string;
+    readonly precision?: number;
+}
+/** Operator-authored per-device display override. Rides the `DeviceMeta`
+ *  lifecycle (persist/preserve/project/pre-seed) — deliberately NOT a new
+ *  cap/store. All fields optional; an empty object is equivalent to absent.
+ *  `unit` triggers render-time conversion when same-dimension as the live
+ *  slice unit (storage stays in source units); `precision` applies AFTER
+ *  conversion; `hidden` removes the device from list surfaces (distinct from
+ *  the HA-only accessories-cap `hiddenChildIds` mechanism). */
+export interface DeviceDisplayOverride {
+    /** Key into ui-library's display icon registry. */
+    readonly icon?: string;
+    /** Overrides the `DEVICE_ROLE_META` label (NOT the device name). */
+    readonly label?: string;
+    /** Canonical spelling (`normalizeUnit` applied at write). */
+    readonly unit?: string;
+    /** Int 0-10, same contract as the slice `precision` field. */
+    readonly precision?: number;
+    readonly hidden?: boolean;
+    readonly perCap?: Readonly<Record<string, DeviceCapDisplayOverride>>;
+}
+/** Operator-authored per-role display default (unit/precision/icon), keyed by
+ *  `DeviceRole` string. Resolution merges these UNDER any per-device
+ *  `DeviceDisplayOverride`. Stored whole-record (full replace) in the
+ *  device-manager addon store's `roleDisplayDefaults` key — NOT on any device's
+ *  meta row. */
+export interface RoleDisplayDefault {
+    readonly unit?: string;
+    readonly precision?: number;
+    readonly icon?: string;
+}
 export interface DeviceMeta {
     readonly id: number;
     readonly stableId: string;
@@ -185,6 +258,12 @@ export interface DeviceMeta {
      *  cap field). Same create/persist/project/restore lifecycle as `childLayout`.
      *  Absent ⇒ no links. Overlaid onto the target cap's `getStatus` at read time. */
     readonly deviceLinks?: DeviceLinks;
+    /** Operator-authored per-device display override (icon/label/unit/precision/
+     *  hidden). Same create/persist/project/restore lifecycle as `deviceLinks`.
+     *  Absent ⇒ no override; the renderer falls back to role default → live slice
+     *  → canonical unit. Applied at RENDER time only — storage stays in source
+     *  units. */
+    readonly display?: DeviceDisplayOverride;
 }
 /**
  * Initial meta a provider supplies on `onCreateDevice`. Differs
@@ -215,6 +294,8 @@ export interface InitialDeviceMeta {
     readonly childLayout?: ChildLayout;
     /** Cross-device field wirings set at create. Mirrors `DeviceMeta.deviceLinks`. */
     readonly deviceLinks?: DeviceLinks;
+    /** Per-device display override set at create. Mirrors `DeviceMeta.display`. */
+    readonly display?: DeviceDisplayOverride;
 }
 /**
  * Single-call payload returned by `BaseDeviceProvider.onCreateDevice`.

package/dist/device/index.d.ts

@@ -11,7 +11,7 @@ export type { IDevice } from './device.js';
 export { DEVICE_PROFILES, BATTERY_DEVICE_PROFILE, deviceMatchesProfile, resolveDeviceProfile, } from './device-profile.js';
 export type { DeviceProfile, DeviceProfileMatch, DeviceProfileDefaults, PipelinePhaseMode, } from './device-profile.js';
 export type { ICameraDevice, StreamSourceEntry } from './camera-device.js';
-export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec, ChildLayout, ChildLayoutEntry, DeviceLinkSource, DeviceLinkTarget, DeviceLinkTransform, DeviceLink, DeviceLinks, } from './device-management.js';
+export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec, ChildLayout, ChildLayoutEntry, DeviceLinkFieldSource, DeviceLinkLiteralSource, DeviceLinkGlobalSource, DeviceLinkExpressionBinding, DeviceLinkExpressionSource, DeviceLinkSource, DeviceLinkTarget, DeviceLinkTransform, DeviceLink, DeviceLinks, } from './device-management.js';
 export { zodEntriesToConfigUI } from './zod-to-config-ui.js';
 export type { DeviceConfigEntry } from './zod-to-config-ui.js';
 export { createRuntimeStateBridge } from './runtime-state-helpers.js';
@@ -19,5 +19,5 @@ export type { RuntimeStateBridge } from './runtime-state-helpers.js';
 export type { IDeviceRuntimeState, Snapshot as RuntimeStateSnapshot, } from './device-runtime-state.js';
 export { getByPath, setByPath } from './path-util.js';
 export { applyTransform } from './device-link-transform.js';
-export { enumerateSchemaFields } from './schema-fields.js';
+export { enumerateItemArrayFields, enumerateSchemaFields } from './schema-fields.js';
 export type { WireableField } from './schema-fields.js';

package/dist/device/schema-fields.d.ts

@@ -3,9 +3,22 @@ export interface WireableField {
     readonly path: string;
     readonly kind: 'string' | 'number' | 'boolean' | 'enum';
     readonly enumValues?: readonly string[];
+    /** True when `path` is relative to ONE item of an item-array cap (see
+     *  `CapabilityStatusItemArray`) — a link targeting it must carry a
+     *  `target.itemKey`. Absent/false for plain status fields. */
+    readonly item?: boolean;
 }
 /** Walk a cap status schema into flat wireable leaf fields (dotted paths).
  *  Recurses into nested ZodObject (unwrapping nullable/optional/default first),
  *  so fields with null live values are still offered. Arrays / unknown shapes
  *  are skipped — never throws. */
 export declare function enumerateSchemaFields(schema: z.ZodType, prefix?: string): readonly WireableField[];
+/** Enumerate the per-item wireable fields of an item-array cap (see
+ *  `CapabilityStatusItemArray`): the item schema's leaf fields, minus the
+ *  `keyField` (the key comes from the link's `itemKey`, never from a wired
+ *  source), each tagged `item: true` so the authoring UI collects an
+ *  `itemKey` alongside the field. Never throws. */
+export declare function enumerateItemArrayFields(itemArray: {
+    readonly keyField: string;
+    readonly itemSchema: z.ZodType;
+}): readonly WireableField[];

package/dist/expression/ast.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AST for the safe expression mini-language.
+ *
+ * SECURITY BY CONSTRUCTION (spec §4 rule 3): there is deliberately NO member
+ * node, NO index node, NO assignment node and NO lambda/function node in this
+ * union. `a.b`, `a["b"]`, `a = b` and `() => …` are therefore UNREPRESENTABLE —
+ * `__proto__` / `constructor` / `prototype` traversal is impossible at the type
+ * level, not by a runtime denylist. `ExpressionCallNode.callee` is a plain
+ * string (a builtin name), never a node, so a computed call like `(min)(1)` is
+ * unparseable.
+ *
+ * The value domain is the four JSON primitives — no objects, arrays or
+ * functions ever flow through the evaluator.
+ */
+/** The only value types the engine produces or consumes. */
+export type ExpressionValue = number | string | boolean | null;
+export type ExpressionBinaryOperator = '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '<' | '<=' | '>' | '>=';
+export type ExpressionLogicalOperator = '&&' | '||';
+export type ExpressionUnaryOperator = '-' | '!';
+export interface ExpressionLiteralNode {
+    readonly kind: 'literal';
+    readonly value: ExpressionValue;
+}
+export interface ExpressionIdentifierNode {
+    readonly kind: 'identifier';
+    readonly name: string;
+}
+export interface ExpressionUnaryNode {
+    readonly kind: 'unary';
+    readonly op: ExpressionUnaryOperator;
+    readonly operand: ExpressionNode;
+}
+export interface ExpressionBinaryNode {
+    readonly kind: 'binary';
+    readonly op: ExpressionBinaryOperator;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+export interface ExpressionLogicalNode {
+    readonly kind: 'logical';
+    readonly op: ExpressionLogicalOperator;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+export interface ExpressionConditionalNode {
+    readonly kind: 'conditional';
+    readonly test: ExpressionNode;
+    readonly consequent: ExpressionNode;
+    readonly alternate: ExpressionNode;
+}
+export interface ExpressionCallNode {
+    readonly kind: 'call';
+    readonly callee: string;
+    readonly args: readonly ExpressionNode[];
+}
+export type ExpressionNode = ExpressionLiteralNode | ExpressionIdentifierNode | ExpressionUnaryNode | ExpressionBinaryNode | ExpressionLogicalNode | ExpressionConditionalNode | ExpressionCallNode;

package/dist/expression/builtins.d.ts

@@ -0,0 +1,19 @@
+import type { ExpressionValue } from './ast.js';
+/** Optional runtime hooks the evaluator threads through to builtins. Stage U
+ *  installs the real unit-conversion table here; absent → the `convert` stub. */
+export interface ExpressionEvalHooks {
+    /** Convert `value` from unit `from` to unit `to`; `null` when the pair is
+     *  not convertible. Absent hook → `convert` uses its identity-only stub. */
+    readonly convert?: (value: number, from: string, to: string) => number | null;
+}
+export interface ExpressionBuiltin {
+    readonly minArgs: number;
+    /** `Number.POSITIVE_INFINITY` for variadic builtins. */
+    readonly maxArgs: number;
+    readonly apply: (args: readonly ExpressionValue[], hooks: ExpressionEvalHooks) => ExpressionValue;
+}
+/** Frozen, null-prototype builtin table. */
+export declare const EXPRESSION_BUILTINS: Readonly<Record<string, ExpressionBuiltin>>;
+/** The set of valid builtin names — used by the parser to reject unknown
+ *  callees at parse time (immediate author feedback). */
+export declare const EXPRESSION_BUILTIN_NAMES: ReadonlySet<string>;

package/dist/expression/compile.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedExpression } from './parser.js';
+export type CompileResult = {
+    readonly ok: true;
+    readonly parsed: ParsedExpression;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** Compile `source` to a `ParsedExpression`, throwing `ExpressionParseError`
+ *  on failure. LRU/negative-cached. */
+export declare function compileExpression(source: string): ParsedExpression;
+/** Compile `source`, returning a discriminated result instead of throwing.
+ *  Used by read paths that must degrade rather than raise. LRU/negative-cached. */
+export declare function compileExpressionSafe(source: string): CompileResult;
+/** Test-only: clear the module-level cache. Not part of the public engine
+ *  surface — used to make cache-behaviour assertions deterministic. */
+export declare function __clearExpressionCompileCache(): void;

package/dist/expression/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error types for the safe expression engine. Two distinct classes so callers
+ * can tell a compile-time (grammar) failure from a runtime (evaluation)
+ * failure — both are non-fatal to the host: read paths degrade to "skip link".
+ */
+/** Thrown by the tokenizer / parser. Carries a 0-based source `position` when
+ *  the failure is anchored to a character (author-facing inline feedback). */
+export declare class ExpressionParseError extends Error {
+    readonly position?: number;
+    constructor(message: string, position?: number);
+}
+/** Thrown by the evaluator (unknown identifier, type mismatch, non-finite
+ *  result, unknown builtin, step-budget exceeded). */
+export declare class ExpressionEvalError extends Error {
+    constructor(message: string);
+}

package/dist/expression/evaluator.d.ts

@@ -0,0 +1,14 @@
+import { type ExpressionEvalHooks } from './builtins.js';
+import type { ExpressionNode, ExpressionValue } from './ast.js';
+export interface ExpressionEvalOptions {
+    readonly hooks?: ExpressionEvalHooks;
+    readonly maxSteps?: number;
+}
+/** Build a null-prototype scope from own-enumerable binding entries. Inherited
+ *  keys of the input (e.g. from a `{__proto__: {...}}` payload) are NOT copied,
+ *  so nothing smuggles in via the prototype chain. */
+export declare function createExpressionScope(bindings: Readonly<Record<string, ExpressionValue>>): Record<string, ExpressionValue>;
+/** Evaluate an AST node against a scope. Throws `ExpressionEvalError` on any
+ *  runtime failure (unknown identifier, type mismatch, non-finite result,
+ *  step-budget exhaustion). */
+export declare function evaluateAst(node: ExpressionNode, scope: Record<string, ExpressionValue>, opts?: ExpressionEvalOptions): ExpressionValue;

package/dist/expression/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Safe expression engine — public surface. A non-Turing-complete infix
+ * mini-language (tokenizer → Pratt parser → whitelisted-AST interpreter) with
+ * NO eval / new Function / node:vm, NO member access, NO loops/lambdas, and
+ * hard resource bounds. Powers the `expression` DeviceLinkSource kind.
+ *
+ * This is the module barrel; leaf files inside @camstack/types MUST import from
+ * the deep modules (e.g. `../expression/compile.js`), never through this file
+ * OR the root barrel (see biome-plugins/no-types-barrel-leaf-import.grit).
+ */
+export type { ExpressionValue, ExpressionNode, ExpressionLiteralNode, ExpressionIdentifierNode, ExpressionUnaryNode, ExpressionBinaryNode, ExpressionLogicalNode, ExpressionConditionalNode, ExpressionCallNode, ExpressionBinaryOperator, ExpressionLogicalOperator, ExpressionUnaryOperator, } from './ast.js';
+export { ExpressionParseError, ExpressionEvalError } from './errors.js';
+export { MAX_EXPRESSION_SOURCE_LENGTH, MAX_EXPRESSION_AST_NODES, MAX_EXPRESSION_EVAL_STEPS, MAX_EXPRESSION_BINDINGS, MAX_EXPRESSION_CALL_ARGS, EXPRESSION_COMPILE_CACHE_CAPACITY, EXPRESSION_IDENTIFIER_RE, RESERVED_BINDING_NAMES, } from './limits.js';
+export { tokenize } from './tokenizer.js';
+export type { Token, Punctuator, Keyword } from './tokenizer.js';
+export { parseExpression } from './parser.js';
+export type { ParsedExpression } from './parser.js';
+export { EXPRESSION_BUILTINS, EXPRESSION_BUILTIN_NAMES, } from './builtins.js';
+export type { ExpressionBuiltin, ExpressionEvalHooks } from './builtins.js';
+export { createExpressionScope, evaluateAst } from './evaluator.js';
+export type { ExpressionEvalOptions } from './evaluator.js';
+export { compileExpression, compileExpressionSafe } from './compile.js';
+export type { CompileResult } from './compile.js';
+export { EXPRESSION_INJECTED_NOW, toExpressionValue, validateExpressionSource, evaluateLinkExpression, } from './link-expression.js';
+export type { ExpressionSourceInput, EvaluateLinkExpressionResult, } from './link-expression.js';

package/dist/expression/limits.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resource-bound constants for the safe expression engine.
+ *
+ * Every bound is defense-in-depth: the grammar is non-Turing-complete (no
+ * loops, recursion, lambdas or member access — see `ast.ts`), so evaluation is
+ * O(nodeCount) by construction. These caps merely put a hard ceiling on the
+ * work a single author-supplied expression can request, so a hostile or
+ * accidental pathological string can never spend unbounded CPU/memory.
+ */
+/** Max source length (chars) — checked BEFORE tokenizing so a huge string is
+ *  rejected without allocation. */
+export declare const MAX_EXPRESSION_SOURCE_LENGTH = 2048;
+/** Max AST nodes — checked during parse; a deeply nested grouping that exceeds
+ *  this is rejected as "expression too complex". */
+export declare const MAX_EXPRESSION_AST_NODES = 256;
+/** Defense-in-depth walker step budget — one increment per node visit during
+ *  evaluation. The grammar guarantees O(nodeCount) walks, so this can only trip
+ *  on a crafted maximum-size AST. */
+export declare const MAX_EXPRESSION_EVAL_STEPS = 4096;
+/** Max named bindings on one `DeviceLinkExpressionSource`. */
+export declare const MAX_EXPRESSION_BINDINGS = 32;
+/** Max positional arguments to any builtin call. */
+export declare const MAX_EXPRESSION_CALL_ARGS = 16;
+/** LRU compile-cache capacity (parsed ASTs keyed by raw source string). */
+export declare const EXPRESSION_COMPILE_CACHE_CAPACITY = 256;
+/** A legal binding / identifier name. */
+export declare const EXPRESSION_IDENTIFIER_RE: RegExp;
+/** Binding names an author may NOT use: `now` is auto-injected; the literal
+ *  keywords lex as values, not identifiers, so binding to them is meaningless. */
+export declare const RESERVED_BINDING_NAMES: ReadonlySet<string>;

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[];