@vxil/feature-configs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 techmaker.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/hooks.d.ts

@@ -0,0 +1,167 @@
+export declare const HOOK_LIMITS: {
+    readonly maxSourceLen: 2000;
+    readonly maxTokens: 600;
+    readonly maxNodes: 250;
+    readonly maxDepth: 40;
+    readonly maxEvalSteps: 5000;
+    readonly maxStringLen: 4096;
+    readonly maxNumberMagnitude: 1000000000000000;
+    readonly maxReadEvalStepsPerRequest: 250000;
+    readonly maxReadHooksPerCollection: 10;
+};
+/** The ONLY root variables an expression may reference. `caller` is the VERIFIED
+ *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  populated ONLY on the READ path (runReadHooks); on the write path and in
+ *  server-caller mode it is null, exactly like `before` on a create. It carries
+ *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`
+ *  ('end_user' | 'tenant'). It is the missing "caller/session context" a read
+ *  hook keys on to redact/derive per-viewer. */
+export declare const HOOK_ROOT_VARS: readonly ["item", "before", "now", "caller"];
+/** The ONLY callable functions. Each is pure + deterministic + bounded. */
+export declare const HOOK_FUNCTIONS: readonly ["min", "max", "abs", "round", "floor", "ceil", "sqrt", "pow", "sign", "len", "lower", "upper", "trim", "substr", "contains", "startsWith", "endsWith", "concat", "coalesce", "ifNull", "not", "isNull", "number", "string", "bool", "daysBetween", "yearsBetween"];
+export type Node = {
+    t: 'num';
+    v: number;
+} | {
+    t: 'str';
+    v: string;
+} | {
+    t: 'bool';
+    v: boolean;
+} | {
+    t: 'null';
+} | {
+    t: 'var';
+    name: string;
+} | {
+    t: 'member';
+    obj: Node;
+    prop: string;
+} | {
+    t: 'unary';
+    op: '!' | '-';
+    arg: Node;
+} | {
+    t: 'bin';
+    op: BinOp;
+    l: Node;
+    r: Node;
+} | {
+    t: 'tern';
+    c: Node;
+    a: Node;
+    b: Node;
+} | {
+    t: 'call';
+    fn: string;
+    args: Node[];
+};
+type BinOp = '||' | '&&' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '+' | '-' | '*' | '/' | '%';
+export declare class HookParseError extends Error {
+}
+export declare class HookEvalError extends Error {
+}
+/** Thrown by a `validate` hook whose expression is falsy — maps to a clean 422. */
+export declare class HookRejection extends Error {
+}
+/** Parse a hook expression into an AST. Throws HookParseError on any malformed input. */
+export declare function parseExpr(src: string): Node;
+/** Walk the AST and reject anything outside the allow-list, plus depth bounds.
+ *  Returns an array of human-readable errors (empty = safe). Pure, no eval. */
+export declare function validateAst(root: Node): string[];
+/** The VERIFIED caller/session context for read hooks (design §5.6). Read-only;
+ *  present only on the read path in end-user mode. In server mode / write path
+ *  the whole object is null. */
+export interface HookCaller {
+    /** the verified end-user session sub, or null in server-caller mode. */
+    endUserId: string | null;
+    /** 'end_user' when a session was verified at the edge, else 'tenant'. */
+    principal: 'end_user' | 'tenant';
+}
+export interface HookContext {
+    item: Record<string, unknown>;
+    before: Record<string, unknown> | null;
+    now: string;
+    /** verified caller/session context (read path only); null otherwise. */
+    caller?: HookCaller | null;
+}
+/** A mutable step counter SHARED across many evalExpr calls (the read path's
+ *  whole-page budget). Checked against maxReadEvalStepsPerRequest. */
+export interface EvalBudget {
+    steps: number;
+}
+/** Evaluate a validated AST against the context. Bounded by a per-expression
+ *  eval-step budget, plus an optional SHARED budget spanning many evaluations
+ *  (runReadHooks passes one per request so a page of rows shares one bound). */
+export declare function evalExpr(root: Node, ctx: HookContext, shared?: EvalBudget): unknown;
+export interface HookDef {
+    collection: string;
+    event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' | 'beforeRead' | 'afterRead';
+    kind: 'validate' | 'derive' | 'redact';
+    expr: string;
+    field?: string;
+    message?: string;
+    enabled?: boolean;
+}
+/** Config-WRITE-time validation of one hook (the anti-malice gate). Returns
+ *  errors (empty = safe to publish). Does NOT need the collection's field list. */
+export declare function validateHookDef(id: string, def: HookDef): string[];
+/** Validate a whole hooks bag (CmsConfig.hooks) at config time. */
+export declare function validateHooksConfig(hooks: Record<string, HookDef> | undefined): string[];
+export interface HookRunResult {
+    data: Record<string, unknown>;
+    derived: string[];
+}
+/** Run all matching write hooks for (collection, phase) over the candidate data.
+ *  Mutates a CLONE: derive hooks set fields; a validate hook that returns falsy
+ *  throws HookRejection (→ the caller maps to a 422 and the tx rolls back).
+ *  Throws HookEvalError on a runtime fault (also a clean 422, never a 500). */
+export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string): HookRunResult;
+export interface ReadHookResult {
+    /** Surviving rows in input order. Each is a SHALLOW COPY with a copied `data`
+     *  bag — the caller's rows are never mutated and nothing here is persisted. */
+    rows: Record<string, unknown>[];
+    /** Rows removed by a falsy beforeRead validate (the visibility filter). */
+    dropped: number;
+}
+/** Run the tenant's READ hooks for a collection over a page of PROJECTED rows
+ *  (each row an item envelope whose `data` already carries computed fields and
+ *  $expand results — that is the cross-field surface an expression reads).
+ *
+ *  Per row, in order:
+ *    1. beforeRead `validate` — a falsy expression DROPS the row (visibility
+ *       filter; a dropped row is indistinguishable from a missing one).
+ *    2. afterRead `derive`   — sets data[field] on the OUTPUT copy only
+ *       (scalar-only, same guard as the write path; NEVER persisted).
+ *    3. afterRead `redact`   — deletes data[field] when the expression is truthy.
+ *
+ *  Context per row: { item: the projected data, before: null, now: ONE ISO
+ *  string for the whole request } — deterministic across the page. The entire
+ *  page shares ONE eval-step budget (HOOK_LIMITS.maxReadEvalStepsPerRequest),
+ *  which is the list path's per-request CPU bound; exhausting it throws
+ *  HookEvalError (→ a clean 422, never a pinned isolate). Write events never
+ *  fire here, and read events never fire in runWriteHooks. */
+export declare function runReadHooks(hooks: Record<string, HookDef> | undefined, collection: string, rows: ReadonlyArray<Record<string, unknown>>, now: string, 
+/** verified caller/session context (design §5.6) — read-only, exposed to
+ *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
+ *  (server-caller mode). */
+caller?: HookCaller | null): ReadHookResult;
+export interface ExprRef {
+    root: 'item' | 'before' | 'now' | 'caller';
+    /** dotted path under the root, e.g. item.profile.age → ['profile','age']. */
+    path: string[];
+}
+/** Collect every variable reference an expression reads (its inputs). */
+export declare function extractRefs(root: Node): ExprRef[];
+export type InferredType = 'number' | 'string' | 'boolean' | 'null' | 'unknown';
+/** Best-effort static type of an expression's result (its output). 'unknown' for
+ *  member access / coalesce / mixed ternaries — never a false-positive mismatch. */
+export declare function inferType(nd: Node): InferredType;
+export type HlKind = 'num' | 'str' | 'fn' | 'var' | 'kw' | 'op' | 'ident' | 'ws' | 'err';
+/** Token-level highlighter over the FULL source (whitespace + bad chars kept),
+ *  so a dashboard editor can render a colored overlay behind a textarea. */
+export declare function highlightTokens(src: string): Array<{
+    value: string;
+    kind: HlKind;
+}>;
+export {};