arrowbase 0.1.1

package/dist/query-CzV9E57Y.d.ts

@@ -0,0 +1,279 @@
+import { R as RowValue, C as Collection } from './collection-DGlKgOGi.js';
+
+/**
+ * Column-op filter DSL. A vectorizable alternative to `.where(fn)`.
+ *
+ * The surface is deliberately tiny — eq/neq/gt/gte/lt/lte for scalars,
+ * and/or/not for composition, plus a column-ref helper. Predicates built
+ * here are compiled to a `RowTest` closure that reads directly from the
+ * column typed-arrays, skipping proxy allocation and per-row row-object
+ * materialization. Anything outside this surface still works via
+ * `.where(fn)` at normal (proxy) speed.
+ *
+ * Example:
+ *   import { query, f, eq, and, gt } from 'arrowbase';
+ *   query(c).filter(and(eq(f('tag'), 'asphalt'), gt(f('speed'), 40)));
+ */
+type Scalar = number | bigint | boolean | string | null;
+/** A reference to a column by name. */
+interface ColumnRef {
+    readonly kind: 'col';
+    readonly name: string;
+}
+interface LiteralNode {
+    readonly kind: 'lit';
+    readonly value: Scalar;
+}
+type Operand = ColumnRef | LiteralNode;
+type CmpOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
+interface CompareNode {
+    readonly kind: 'cmp';
+    readonly op: CmpOp;
+    readonly left: Operand;
+    readonly right: Operand;
+}
+interface AndNode {
+    readonly kind: 'and';
+    readonly args: readonly FilterExpr[];
+}
+interface OrNode {
+    readonly kind: 'or';
+    readonly args: readonly FilterExpr[];
+}
+interface NotNode {
+    readonly kind: 'not';
+    readonly arg: FilterExpr;
+}
+interface IsNullNode {
+    readonly kind: 'isNull';
+    readonly col: ColumnRef;
+    readonly negated: boolean;
+}
+interface InNode {
+    readonly kind: 'in';
+    readonly col: ColumnRef;
+    readonly values: readonly Scalar[];
+}
+/**
+ * String predicate. Covers the common text-matching cases with a
+ * vectorizable shape so the kernel can pre-compute (e.g., the matching
+ * set of dict codes) instead of walking characters per row.
+ *
+ * `op`:
+ *  - `contains` / `startsWith` / `endsWith`: plain substring match.
+ *  - `like`: SQL LIKE, with `%` = any sequence, `_` = any single char,
+ *    and `\` as an escape for literal `%` / `_`.
+ *  - `matches`: raw RegExp pattern (string + optional flags) run with
+ *    `RegExp.prototype.test`. Use sparingly; engines inline the other
+ *    ops much more aggressively.
+ *
+ * `caseInsensitive` performs ASCII-fold case folding (fast). For
+ * locale-aware folding (German ß, Turkish dotted-I, etc.) use
+ * `matches` with an explicit RegExp containing the `i` flag, which the
+ * engine delegates to the platform.
+ */
+type StringOp = 'contains' | 'startsWith' | 'endsWith' | 'like' | 'matches';
+interface StringOpNode {
+    readonly kind: 'str';
+    readonly op: StringOp;
+    readonly col: ColumnRef;
+    /** Pattern or substring. For `matches`, the regex source. */
+    readonly value: string;
+    /** Flags (for `matches` only). Ignored for other ops. */
+    readonly flags?: string;
+    /** ASCII-fold case-insensitive compare. Ignored by `matches`. */
+    readonly caseInsensitive?: boolean;
+    /** If true, the match result is inverted (NOT contains/like/...). */
+    readonly negated?: boolean;
+}
+type FilterExpr = CompareNode | AndNode | OrNode | NotNode | IsNullNode | InNode | StringOpNode | ColumnRef;
+/** Build a column ref. `f('speed')` reads shorter at the call site. */
+declare function f(name: string): ColumnRef;
+declare function eq(a: Operand | Scalar, b: Operand | Scalar): CompareNode;
+declare function neq(a: Operand | Scalar, b: Operand | Scalar): CompareNode;
+declare function gt(a: Operand | Scalar, b: Operand | Scalar): CompareNode;
+declare function gte(a: Operand | Scalar, b: Operand | Scalar): CompareNode;
+declare function lt(a: Operand | Scalar, b: Operand | Scalar): CompareNode;
+declare function lte(a: Operand | Scalar, b: Operand | Scalar): CompareNode;
+declare function and(...args: FilterExpr[]): AndNode;
+declare function or(...args: FilterExpr[]): OrNode;
+declare function not(arg: FilterExpr): NotNode;
+declare function isNull(col: ColumnRef): IsNullNode;
+declare function isNotNull(col: ColumnRef): IsNullNode;
+declare function inArray(col: ColumnRef, values: readonly Scalar[]): InNode;
+interface StringOpOptions {
+    /** ASCII-fold case-insensitive. Ignored by `matches`. */
+    caseInsensitive?: boolean;
+    /** Invert match. */
+    negated?: boolean;
+}
+declare function contains(col: ColumnRef, value: string, opts?: StringOpOptions): StringOpNode;
+declare function startsWith(col: ColumnRef, value: string, opts?: StringOpOptions): StringOpNode;
+declare function endsWith(col: ColumnRef, value: string, opts?: StringOpOptions): StringOpNode;
+declare function like(col: ColumnRef, pattern: string, opts?: StringOpOptions): StringOpNode;
+declare function matches(col: ColumnRef, pattern: string | RegExp, opts?: StringOpOptions): StringOpNode;
+
+type Predicate = (row: RowValue) => boolean;
+type SortDir = 'asc' | 'desc';
+interface JoinSpecLike {
+    readonly on: {
+        readonly left: string;
+        readonly right: string;
+    };
+    readonly as: string;
+    readonly type?: 'inner';
+}
+type JoinQueryLike = any;
+interface OrderSpec {
+    readonly column: string;
+    readonly dir: SortDir;
+}
+/**
+ * Immutable query spec. Each builder method returns a new Query. Deps are
+ * either `'all'` (everything) or a concrete set of column names. When a
+ * predicate is present and no explicit `.deps(...)` override was applied,
+ * deps are inferred on first evaluation via the tracking proxy and grow
+ * monotonically over time.
+ */
+declare class Query<TRow extends RowValue = RowValue> {
+    readonly collection: Collection;
+    readonly predicate: Predicate | null;
+    /** Column-op filter DSL expression (vectorizable). */
+    readonly filterExpr: FilterExpr | null;
+    readonly selection: readonly string[] | null;
+    readonly order: readonly OrderSpec[];
+    readonly limitN: number | null;
+    readonly offsetN: number;
+    /** Explicit deps override. If null, deps are inferred. */
+    readonly explicitDeps: ReadonlySet<string> | null;
+    constructor(collection: Collection, predicate?: Predicate | null, selection?: readonly string[] | null, order?: readonly OrderSpec[], limitN?: number | null, offsetN?: number, explicitDeps?: ReadonlySet<string> | null, filterExpr?: FilterExpr | null);
+    where(predicate: Predicate): Query<TRow>;
+    /**
+     * Add a vectorizable column-op filter. Composes with prior `filter()`
+     * calls via AND. Anything that fits the `FilterExpr` DSL takes the
+     * vectorized fast path in `QueryExecutor`; combine with `.where(fn)`
+     * when you need an escape hatch for logic outside the DSL — the fast
+     * path still runs first for the DSL portion.
+     */
+    filter(expr: FilterExpr): Query<TRow>;
+    select(columns: readonly string[]): Query<TRow>;
+    orderBy(column: string, dir?: SortDir): Query<TRow>;
+    limit(n: number): Query<TRow>;
+    offset(n: number): Query<TRow>;
+    /**
+     * Equijoin against another collection. Returns a `JoinQuery` that
+     * exposes the post-join builder surface (where / select / orderBy /
+     * limit / offset).
+     *
+     * ```ts
+     * query(orders)
+     *   .filter(f('amount').gt(100))
+     *   .join(users, { on: { left: 'userId', right: '__id' }, as: 'user' })
+     *   .orderBy('user.name')
+     *   .select(['id', 'amount', 'user.name']);
+     * ```
+     *
+     * Implementation: to avoid a static cycle between query.ts and
+     * join.ts, join.ts registers its factory via `registerJoinFactory`
+     * at module-load time. Importing `arrowbase` (or
+     * `arrowbase/query/join`) before calling `.join()` is sufficient.
+     */
+    join(right: Collection, spec: JoinSpecLike): JoinQueryLike;
+    /**
+     * Explicit dep override. Use this when:
+     *   - your predicate reads columns conditionally and you want stable deps
+     *   - you want to force reactivity on a superset of columns
+     */
+    deps(columns: readonly string[]): Query<TRow>;
+    /** Columns that must be materialized for this query (deps + filter + selection + order). */
+    requiredColumns(inferredDeps: ReadonlySet<string>): ReadonlySet<string>;
+    private requireKnownColumn;
+}
+/**
+ * Snapshot = result of evaluating a Query at a specific global version.
+ * Rows are plain JS objects shaped by `selection` (or full rows if null).
+ */
+interface QuerySnapshot<TRow extends RowValue = RowValue> {
+    readonly rows: readonly TRow[];
+    /** Collection.globalVersion at the moment of the snapshot. */
+    readonly version: number;
+}
+/**
+ * Executor = caches the last snapshot + dep set for a Query so we can skip
+ * recomputation when only untouched columns changed.
+ *
+ * Executors are created by `run(query)` and held by callers (including the
+ * subscribe wrapper below). A single Query instance may have multiple
+ * executors in flight; each owns its own cache.
+ */
+declare class QueryExecutor<TRow extends RowValue = RowValue> {
+    readonly query: Query<TRow>;
+    private deps;
+    private cachedSnapshot;
+    /** Per-column version seen at the time `cachedSnapshot` was produced. */
+    private cachedVersions;
+    /**
+     * When the predicate trips (throws) during the tracking dry-run, we
+     * fall back to `deps = all`. We still try inference again after the
+     * predicate changes, but a single Query instance keeps this bit sticky.
+     */
+    private depsAreAll;
+    /**
+     * Inserts, deletes, and rollbacks invalidate any cached snapshot because
+     * they may change the live row set even when no observed value column
+     * moves (soft-delete notwithstanding). We flip this flag from a passive
+     * change listener and clear it on recompute.
+     */
+    private staleFromInsertOrDelete;
+    private readonly unsubscribePassive;
+    constructor(query: Query<TRow>);
+    /** Release the passive change listener. */
+    dispose(): void;
+    /** True if the cached snapshot is still valid given current column versions. */
+    private cacheIsFresh;
+    /**
+     * Columns this query observes for invalidation purposes. Includes:
+     *   - inferred or explicit deps (from predicate / .deps())
+     *   - selection columns (stale projection otherwise)
+     *   - order-by columns (stale sort otherwise)
+     */
+    private observedColumns;
+    /** Lazily compile the filterExpr. Cached for executor lifetime. */
+    private compiledFilter;
+    private compiledFilterExpr;
+    private compiledFilterError;
+    private getCompiledFilter;
+    /** Recompute the snapshot, updating cache. */
+    private recompute;
+    /** Legacy scan: materialize + run fn predicate with dep tracking. Returns ordinals of survivors. */
+    private legacyScan;
+    /**
+     * Map the sequential index returned by `rows()` to the live row
+     * ordinal. `rows()` yields in the same order as `_internalLiveOrdinals()`,
+     * so we lazily keep a parallel ordinal buffer.
+     */
+    private cachedOrdinalBuffer;
+    private cachedOrdinalVersion;
+    private getOrdinalFor;
+    /** Apply the fn predicate to a candidate ordinal set (post-kernel filter). */
+    private applyFnPredicate;
+    private materializeFullRow;
+    /** Return a snapshot, reusing the cached one if all observed columns are unchanged. */
+    snapshot(): QuerySnapshot<TRow>;
+    /**
+     * Subscribe to reactive updates. `listener` fires once with the initial
+     * snapshot and then again after every mutation that touches an observed
+     * column. Returns an unsubscribe function.
+     */
+    subscribe(listener: (snap: QuerySnapshot<TRow>) => void): () => void;
+    /** Visible for tests: introspect current inferred deps. */
+    get inferredDeps(): ReadonlySet<string>;
+    get isDepsAll(): boolean;
+    private shouldReact;
+}
+/** Shorthand entry point: `query(collection).where(...).select(...)`. */
+declare function query<TRow extends RowValue = RowValue>(collection: Collection): Query<TRow>;
+/** Build an executor for a Query. */
+declare function run<TRow extends RowValue = RowValue>(q: Query<TRow>): QueryExecutor<TRow>;
+
+export { type ColumnRef as C, type FilterExpr as F, type InNode as I, type OrderSpec as O, type Predicate as P, Query as Q, type SortDir as S, type Scalar as a, QueryExecutor as b, type QuerySnapshot as c, type StringOp as d, type StringOpNode as e, type StringOpOptions as f, f as g, and as h, contains as i, endsWith as j, eq as k, gt as l, gte as m, inArray as n, isNotNull as o, isNull as p, like as q, lt as r, lte as s, matches as t, neq as u, not as v, or as w, startsWith as x, query as y, run as z };

package/dist/react.d.ts

@@ -0,0 +1,51 @@
+import { R as RowValue, C as Collection } from './collection-DGlKgOGi.js';
+import { c as QuerySnapshot, Q as Query } from './query-CzV9E57Y.js';
+
+/**
+ * Subscribe a React component to a Query. Returns the latest snapshot
+ * (`{ rows, version }`); the component re-renders when the query's
+ * observed columns change.
+ *
+ * The executor is created on first mount and cached for the lifetime of
+ * the owning component (not the Query instance). When the query
+ * identity changes between renders, a fresh executor is created and
+ * the previous one is disposed.
+ *
+ * ```tsx
+ * const q = useMemo(() => query(users).filter(fEq(f('active'), true)), [users]);
+ * const { rows } = useLiveQuery(q);
+ * return <ul>{rows.map(r => <li key={r.__id}>{r.name}</li>)}</ul>;
+ * ```
+ *
+ * The snapshot `rows` reference is stable across renders when the
+ * executor determined nothing changed (internal caching), so users can
+ * pass it directly into `React.memo`'d children without extra memo.
+ */
+declare function useLiveQuery<TRow extends RowValue>(query: Query<TRow>, options?: UseLiveQueryOptions<TRow>): QuerySnapshot<TRow>;
+interface UseLiveQueryOptions<TRow extends RowValue> {
+    /** Value returned during SSR. Defaults to an empty-rows snapshot. */
+    readonly ssrSnapshot?: QuerySnapshot<TRow>;
+}
+/**
+ * Builder-closure variant. Accepts a function that composes a Query
+ * (typically a `.filter().orderBy()...` chain) and a dependency array
+ * for when to rebuild. This avoids making callers memoize the Query
+ * object themselves.
+ *
+ * ```tsx
+ * const { rows } = useLiveQueryResult(
+ *   users,
+ *   (q) => q.filter(fEq(f('team'), team)).orderBy('name'),
+ *   [team],
+ * );
+ * ```
+ */
+declare function useLiveQueryResult<TRow extends RowValue>(collection: Collection, build: (q: Query<TRow>) => Query<TRow>, deps?: readonly unknown[], options?: UseLiveQueryOptions<TRow>): QuerySnapshot<TRow>;
+/**
+ * Subscribe to a collection's `globalVersion`. Returns a monotonically
+ * increasing number that bumps on every mutation. Useful as a cache-bust
+ * key or a dependency to other hooks.
+ */
+declare function useCollectionVersion(collection: Collection): number;
+
+export { type UseLiveQueryOptions, useCollectionVersion, useLiveQuery, useLiveQueryResult };