@vexcms/core 0.0.20 → 0.1.0-alpha.2

package/dist/access/constraintTypes.d.ts

@@ -0,0 +1,337 @@
+import type { GenericDocument, IndexRangeBuilder } from "convex/server";
+/**
+ * Adds 1 to a number literal via lookup, mirroring Convex's own `PlusOne`
+ * (`convex/src/server/index_range_builder.ts`) — advances the field cursor
+ * `ConstraintBuilder` tracks. Not exported: only `NextConstraintBuilder`
+ * needs it.
+ */
+type PlusOne<N extends number> = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15][N];
+/**
+ * Every operator a Convex `IndexRangeBuilder` exposes at its first
+ * position, derived from the builder's own type rather than hand-listed —
+ * a new upstream method appears here automatically, and a rename fails
+ * compilation instead of silently drifting. Convex's private nominal
+ * markers never surface in `keyof`, so this resolves to exactly
+ * `"eq" | "gt" | "gte" | "lt" | "lte"`.
+ */
+export type IndexOp = Extract<keyof IndexRangeBuilder<GenericDocument, string[], 0>, string>;
+/**
+ * Operators available to an unindexed constraint. The index-range operators
+ * plus `neq`, which `IndexRangeBuilder` has no equivalent for but
+ * `FilterBuilder` does.
+ */
+export type FilterOp = IndexOp | "neq";
+/**
+ * `TDoc`'s explicitly declared keys, with any index signature dropped.
+ *
+ * Generated documents extend `VexDocument` (`api/convex.ts`), which carries
+ * `[key: string]: unknown` so a document can hold schema-defined fields the static
+ * type does not enumerate. The cost is that `keyof` answers `string` rather than a
+ * literal union — which silently removes editor completion for field names and
+ * accepts any string as a field. Remapping with `as string extends K ? never : K`
+ * discards exactly the signature keys and keeps the declared ones.
+ *
+ * @typeParam TDoc - Document shape.
+ * @internal
+ */
+type DeclaredKeys<TDoc> = {
+    [K in keyof TDoc as string extends K ? never : number extends K ? never : K]: TDoc[K];
+};
+/**
+ * `TDoc` with `VexDocument`'s `[key: string]: unknown` index signature removed.
+ *
+ * The signature exists so a document can hold schema-defined fields statically, but it
+ * also makes EVERY property name readable at type level: `data.tpyo` and
+ * `data.neverDeclared` both resolve to `unknown` instead of erroring. That silently
+ * defeats the point of typing a permission callback against its resource.
+ *
+ * Left alone in the pre-generation case (`unknown extends TDoc`), where stripping would
+ * turn the document into `{}` and make every real field unreadable.
+ *
+ * @typeParam TDoc - Document shape, or `unknown` when the registry is unaugmented.
+ */
+export type DeclaredDoc<TDoc> = unknown extends TDoc ? TDoc : DeclaredKeys<TDoc>;
+/**
+ * A constrainable field name for `TDoc`: its declared fields, degrading to `string`
+ * when the document type is unresolved.
+ *
+ * Two widenings are deliberately handled differently.
+ *
+ * Before `vex generate` runs, `DocumentBySlug` falls back to
+ * `Record<string, unknown>`, so a resource's document type resolves to `unknown` —
+ * and `keyof unknown` is `never`, which would make every field name unwritable.
+ * `unknown extends TDoc` is true only for `unknown`/`any`, so this widens exactly
+ * in the pre-generation case.
+ *
+ * After generation the document type is real but still has `VexDocument`'s index
+ * signature, so a bare `keyof` would collapse to `string` — no completion, and a
+ * misspelled field silently accepted with an `unknown` value. {@link DeclaredKeys}
+ * strips it, which is what makes `q.eq("` offer the resource's actual fields and
+ * `q.eq("tset", …)` an error.
+ *
+ * @typeParam TDoc - Document shape, or `unknown` when the registry is unaugmented.
+ */
+export type ConstraintField<TDoc> = unknown extends TDoc ? string : keyof DeclaredKeys<TDoc> & string;
+/**
+ * The value type for a constraint on field `F` of `TDoc`: the field's own type,
+ * `never` when `F` is not a field of `TDoc`, and `unknown` when `TDoc` itself is
+ * unresolved.
+ *
+ * The third case is what separates "you named a field that does not exist" (a real
+ * error, `never`) from "this project has not run `vex generate` yet" (not an error).
+ * Without it both collapse to `never` and no constraint can be written at all —
+ * including in `packages/core`'s own tests, which run against an unaugmented
+ * registry by design.
+ *
+ * @typeParam TDoc - Document shape, or `unknown` when the registry is unaugmented.
+ * @typeParam F - The field name being constrained.
+ */
+export type ConstraintValue<TDoc, F extends string> = unknown extends TDoc ? unknown : F extends keyof TDoc ? TDoc[F] : never;
+/**
+ * One node of an unindexed constraint tree: a comparison on a document field,
+ * or a boolean combination of nodes.
+ *
+ * Unlike {@link AccessIndexConstraint} this is recursive, because `FilterBuilder`
+ * supports `and` / `or` / `not` and an index range does not.
+ */
+export type AccessFilterConstraint<TDoc> = {
+    kind: "compare";
+    field: ConstraintField<TDoc>;
+    op: FilterOp;
+    value: ConstraintValue<TDoc, ConstraintField<TDoc>>;
+} | {
+    kind: "and";
+    nodes: AccessFilterConstraint<TDoc>[];
+} | {
+    kind: "or";
+    nodes: AccessFilterConstraint<TDoc>[];
+} | {
+    kind: "not";
+    node: AccessFilterConstraint<TDoc>;
+};
+/**
+ * Builder for an unindexed constraint — the `q` a rule receives when it
+ * declares no `withIndex` (DD 13).
+ *
+ * Deliberately enforces neither field order nor operator sequencing: it
+ * compiles to `.filter()`, which imposes neither. Every method returns
+ * {@link ConstraintResult}, so this shares the indexed builder's nominal
+ * terminal and needs no positional tracking or terminal states.
+ *
+ * @typeParam TDoc - Document shape for the resource this rule governs.
+ */
+export interface FilterConstraintBuilder<TDoc> {
+    eq<F extends ConstraintField<TDoc>>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    neq<F extends ConstraintField<TDoc>>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    gt<F extends ConstraintField<TDoc>>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    gte<F extends ConstraintField<TDoc>>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    lt<F extends ConstraintField<TDoc>>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    lte<F extends ConstraintField<TDoc>>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    and(...nodes: ConstraintResult[]): ConstraintResult;
+    or(...nodes: ConstraintResult[]): ConstraintResult;
+    not(node: ConstraintResult): ConstraintResult;
+}
+/**
+ * One recorded positional constraint: `field` is pinned to a literal, `op`
+ * is one of {@link IndexOp}, and `value` is typed from the document shape
+ * at that field. This is what a `ConstraintBuilder` chain call records
+ * (`createConstraintBuilder`, `access/createConstraintBuilder.ts`), and
+ * what a later compiler step reads back to build a `withIndex` range, a
+ * `FilterBuilder` expression, or a JS predicate — the same recorded data
+ * feeds all three, which is the reason a builder replaces a callback.
+ *
+ * @typeParam TField - The field name this constraint pins.
+ * @typeParam TDoc - The document shape `value`'s type is read from.
+ */
+export type AccessIndexConstraint<TField extends string, TDoc> = {
+    field: TField;
+    op: IndexOp;
+    value: ConstraintValue<TDoc, TField>;
+};
+/**
+ * Terminal marker for a completed constraint chain. Nominal — a private,
+ * unimplementable member — so a plain object literal can never satisfy it;
+ * only a real chain call (`eq`/`gt`/`gte`/`lt`/`lte`) can produce one. Every
+ * builder stage extends this, so a chain is already assignable to
+ * `ConstraintResult` at the exact point Convex would also accept it as
+ * complete.
+ */
+export declare abstract class ConstraintResult {
+    private _isConstraintResult;
+}
+/**
+ * Upper-bound stage of a constraint chain: only `lt`/`lte` remain. Reached
+ * after a lower bound (Convex allows at most one upper bound, on the same
+ * field, and nothing after it) or directly from `eq` on the index's last
+ * field. Extends {@link ConstraintResult} — a chain that never calls
+ * `lt`/`lte` is already a valid, complete result.
+ *
+ * @typeParam TDoc - Document shape constraint values are typed from.
+ * @typeParam TField - The field this stage's bounds pin to.
+ * @internal
+ */
+export interface UpperBoundConstraintBuilder<TDoc, TField extends string> extends ConstraintResult {
+    lt<F extends TField>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+    lte<F extends TField>(field: F, value: ConstraintValue<TDoc, F>): ConstraintResult;
+}
+/**
+ * Lower-bound stage of a constraint chain: `gt`/`gte` are available, each
+ * closing off further lower bounds but permitting one optional upper bound
+ * via the returned {@link UpperBoundConstraintBuilder}.
+ *
+ * @typeParam TDoc - Document shape constraint values are typed from.
+ * @typeParam TField - The field this stage's bounds pin to.
+ * @internal
+ */
+export interface LowerBoundConstraintBuilder<TDoc, TField extends string> extends UpperBoundConstraintBuilder<TDoc, TField> {
+    gt<F extends TField>(field: F, value: ConstraintValue<TDoc, F>): UpperBoundConstraintBuilder<TDoc, TField>;
+    gte<F extends TField>(field: F, value: ConstraintValue<TDoc, F>): UpperBoundConstraintBuilder<TDoc, TField>;
+}
+/**
+ * After `eq` advances the field cursor to `N + 1`: another {@link
+ * ConstraintBuilder} positioned at the next field, or the terminal {@link
+ * ConstraintResult} when the index is spent (no more fields to constrain).
+ *
+ * @typeParam TFields - The index's field tuple, in declaration order.
+ * @typeParam TDoc - Document shape constraint values are typed from.
+ * @typeParam N - The field cursor position `eq` was just called at.
+ * @internal
+ */
+export type NextConstraintBuilder<TFields extends readonly string[], TDoc, N extends number> = PlusOne<N> extends TFields["length"] ? ConstraintResult : ConstraintBuilder<TFields, TDoc, PlusOne<N>>;
+/**
+ * Position-tracking constraint builder — the type `createConstraintBuilder`
+ * (`access/createConstraintBuilder.ts`) returns, and what a rule's
+ * `constraints` callback receives. `eq` pins the field at cursor `N` and
+ * advances to `N + 1`; `gt`/`gte`/`lt`/`lte` (inherited from {@link
+ * LowerBoundConstraintBuilder}) pin the SAME field and close the chain to
+ * further constraints. This encodes Convex's complete index rule: zero or
+ * more `eq`, then at most one lower bound, then at most one upper bound,
+ * fields strictly in index order with no gaps, each value typed per field —
+ * violating any of these is a compile error, never a runtime one.
+ *
+ * @typeParam TFields - The index's field tuple, in declaration order —
+ *   typically `IndexFieldsFor<slug, indexName>` (`types/generated.ts`).
+ * @typeParam TDoc - Document shape constraint values are typed from.
+ * @typeParam N - The current field cursor. Defaults to `0`, the index's
+ *   first field; only `NextConstraintBuilder` advances it.
+ */
+export interface ConstraintBuilder<TFields extends readonly string[], TDoc, N extends number = 0> extends LowerBoundConstraintBuilder<TDoc, TFields[N] & string> {
+    eq<F extends TFields[N] & string>(field: F, value: ConstraintValue<TDoc, F>): NextConstraintBuilder<TFields, TDoc, N>;
+}
+/**
+ * Terminal marker for a completed access CONDITION — the value a rule's
+ * `constraints` callback returns.
+ *
+ * Deliberately NOT {@link ConstraintResult}. That one marks a completed
+ * *expression* inside one algebra's callback; this marks a completed *condition* on
+ * the query as a whole. Keeping them separate is what makes the mistake
+ * unrepresentable: `FilterConstraintBuilder.and` takes `ConstraintResult`, so an
+ * index condition can never be passed into a boolean combinator. Under a single
+ * shared terminal it type-checked and produced a filter node with no `kind`, which
+ * the compilers silently turned into `undefined` — a rule that appeared to
+ * constrain and did not.
+ *
+ * Nominal for the same reason as `ConstraintResult`: a plain object literal must
+ * not satisfy it, so only a real `q.withIndex(…)` / `q.filter(…)` call can produce
+ * one.
+ */
+export declare abstract class AccessConditionResult {
+    private _isAccessConditionResult;
+}
+/**
+ * An index-backed condition, which may still add a filter.
+ *
+ * Returned by {@link AccessQueryBuilder.withIndex}. Already a complete condition on
+ * its own — return it directly for index-only narrowing — or continue with
+ * `.filter(…)` to add predicates the index range cannot express.
+ *
+ * @typeParam TDoc - Document shape for the resource this rule governs.
+ */
+export interface IndexedAccessCondition<TDoc> extends AccessConditionResult {
+    /**
+     * Adds a per-document predicate alongside the index range.
+     *
+     * Compiles to `.withIndex(name, range).filter(expr)` — Convex's own shape, and
+     * the reason both halves can coexist: the range narrows what is READ, the filter
+     * rejects rows within it that the range cannot describe (`neq`, `or`, `not`).
+     *
+     * @param predicate - Builds the expression from the flat filter algebra.
+     * @returns The completed condition.
+     */
+    filter(predicate: (q: FilterConstraintBuilder<TDoc>) => ConstraintResult): AccessConditionResult;
+}
+/**
+ * The `q` a rule on a NON-query action receives: predicates only.
+ *
+ * The same authoring shape as {@link AccessQueryBuilder} minus `withIndex`, so a
+ * rule reads identically whichever action it guards — `q.filter((f) => …)` either
+ * way. A create/update/delete has no query to narrow, so index pushdown is simply
+ * absent rather than rejected, and `q.withIndex` fails at the call with a
+ * missing-method error rather than as a whole-object shape mismatch (DD 14).
+ *
+ * @typeParam TDoc - Document shape for the resource this rule governs.
+ */
+export interface AccessPredicateBuilder<TDoc> {
+    /**
+     * Narrows by predicate.
+     *
+     * @param predicate - Builds the expression from the flat filter algebra.
+     * @returns The completed condition.
+     */
+    filter(predicate: (q: FilterConstraintBuilder<TDoc>) => ConstraintResult): AccessConditionResult;
+}
+/**
+ * The `q` a query-shaped rule receives.
+ *
+ * Mirrors Convex's own query surface, one layer up — each algebra gets its own
+ * callback with its own builder, and the two never meet in one expression:
+ *
+ * ```ts
+ * // Convex
+ * ctx.db.query("pages")
+ *   .withIndex("by_author", (q) => q.eq("authorId", u))
+ *   .filter((q) => q.neq(q.field("archived"), true));
+ *
+ * // an access rule
+ * q.withIndex("by_author", (ix) => ix.eq("authorId", u))
+ *  .filter((f) => f.neq("archived", true));
+ * ```
+ *
+ * That confinement is load-bearing, not stylistic: `ix` exists only inside the
+ * range callback and `f` only inside the predicate callback, so an index expression
+ * cannot reach a boolean combinator even by accident.
+ *
+ * Selecting the index through a METHOD is also what makes positional typing
+ * reachable — `N` is the method's own type parameter, so the literal at the call
+ * site resolves that index's real field tuple and Convex's field ORDER becomes a
+ * compile error. A sibling property cannot be seen by its neighbour's callback
+ * type, which is why earlier `{ withIndex, constraints }` shapes could only offer
+ * the resource's flat field-key union.
+ *
+ * Rules on mutation actions receive a bare {@link FilterConstraintBuilder} instead
+ * — no query exists to narrow, so `withIndex` is absent rather than rejected.
+ *
+ * @typeParam TDoc - Document shape for the resource this rule governs.
+ * @typeParam TIndexFields - The resource's declared indexes, name → field tuple
+ *   in declaration order (`IndexFieldsBySlug[slug]`, `types/generated.ts`).
+ */
+export interface AccessQueryBuilder<TDoc, TIndexFields extends Record<string, readonly string[]>> extends AccessPredicateBuilder<TDoc> {
+    /**
+     * Narrows the query through a declared index.
+     *
+     * **The range callback is REQUIRED**, unlike Convex's, where it is optional. A
+     * range-less `withIndex` excludes no documents — every row has an index entry, so
+     * it only re-orders, and the docs are explicit that it scans the whole table.
+     * Convex allows it because a caller may legitimately want ordering; an access rule
+     * never does, and a range-less one would read as a restriction while being none.
+     *
+     * @typeParam N - The index name, inferred from the literal passed.
+     * @param name - A declared index on this resource.
+     * @param range - Builds the range. `ix` is positional: Convex's index rules,
+     *   field order included, apply inside it.
+     * @returns A condition that may be returned as-is or continued with `.filter(…)`.
+     */
+    withIndex<N extends keyof TIndexFields & string>(name: N, range: (ix: ConstraintBuilder<TIndexFields[N], TDoc, 0>) => ConstraintResult): IndexedAccessCondition<TDoc>;
+}
+export {};
+//# sourceMappingURL=constraintTypes.d.ts.map

package/dist/access/constraintTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraintTypes.d.ts","sourceRoot":"","sources":["../../src/access/constraintTypes.ts"],"names":[],"mappings":"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"}

package/dist/access/createAccessQueryBuilder.d.ts

@@ -0,0 +1,59 @@
+import type { AccessConditionResult, AccessFilterConstraint, AccessIndexConstraint, AccessQueryBuilder, IndexedAccessCondition } from "./constraintTypes";
+/**
+ * What a rule's `constraints` callback resolved to: the condition on which
+ * documents the caller may read.
+ *
+ * Either half may be present, and **both together is the normal case, not a
+ * conflict** — it is exactly `.withIndex(name, range).filter(expr)`, Convex's own
+ * shape. The range narrows what is READ; the filter rejects rows within that range
+ * which the range cannot describe (`neq`, `or`, `not`).
+ *
+ * Neither present means the callback returned a condition that excludes nothing.
+ * Absence of a condition altogether is `undefined`, not an empty object.
+ *
+ * @typeParam TDoc - Document shape the values are typed against.
+ */
+export interface AccessCondition<TDoc> {
+    /** The index the rule chose, and the range it built on it. */
+    index?: {
+        /** Declared index name passed to `q.withIndex(…)`. */
+        name: string;
+        /** The range, in call order. Never empty — the range callback is required. */
+        constraints: readonly AccessIndexConstraint<string, TDoc>[];
+    };
+    /** Root of the predicate tree, when the rule added or used `filter`. */
+    filter?: AccessFilterConstraint<TDoc>;
+}
+/**
+ * Creates the `q` a query-shaped rule receives.
+ *
+ * Composes the two algebras without letting them mix: `withIndex` runs its range
+ * callback against a fresh positional builder and reads the result; `filter` runs
+ * its predicate callback against a fresh flat builder. Neither builder escapes its
+ * callback, so an index expression can never reach a boolean combinator.
+ *
+ * **Pure, and only the returned value counts.** Nothing accumulates outside a
+ * callback's own return, so a rule that builds a chain and discards it contributes
+ * nothing — dead code behaves like dead code.
+ *
+ * @typeParam TDoc - Document shape constraint values are typed from.
+ * @typeParam TIndexFields - The resource's index name → field tuple map.
+ * @returns A builder whose `withIndex` / `filter` results carry the condition.
+ */
+export declare function createAccessQueryBuilder<TDoc, TIndexFields extends Record<string, readonly string[]>>(): AccessQueryBuilder<TDoc, TIndexFields>;
+/**
+ * Reads the condition a returned terminal carries.
+ *
+ * The counterpart to the casts above: `AccessConditionResult` is nominal and has no
+ * public shape, so only this module can get the condition back out.
+ *
+ * @typeParam TDoc - Document shape the values are typed against.
+ * @param result - The value a rule's `constraints` callback returned.
+ * @returns Its condition, or `undefined` when `result` did not come from this
+ *   module — unreachable through the types, and treated as "no condition" so a rule
+ *   that reached past them cannot silently widen into an unfiltered read.
+ */
+export declare function readAccessCondition<TDoc>(result: AccessConditionResult): AccessCondition<TDoc> | undefined;
+/** Re-exported so the type name travels with its reader. */
+export type { IndexedAccessCondition };
+//# sourceMappingURL=createAccessQueryBuilder.d.ts.map

package/dist/access/createAccessQueryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAccessQueryBuilder.d.ts","sourceRoot":"","sources":["../../src/access/createAccessQueryBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAElB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe,CAAC,IAAI;IACnC,8DAA8D;IAC9D,KAAK,CAAC,EAAE;QACN,sDAAsD;QACtD,IAAI,EAAE,MAAM,CAAC;QACb,8EAA8E;QAC9E,WAAW,EAAE,SAAS,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;KAC7D,CAAC;IACF,wEAAwE;IACxE,MAAM,CAAC,EAAE,sBAAsB,CAAC,IAAI,CAAC,CAAC;CACvC;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EACJ,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,KACnD,kBAAkB,CAAC,IAAI,EAAE,YAAY,CAAC,CAyC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EACtC,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAAC,IAAI,CAAC,GAAG,SAAS,CAUnC;AAED,4DAA4D;AAC5D,YAAY,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/access/createFilterConstraintBuilder.d.ts

@@ -0,0 +1,26 @@
+import type { FilterConstraintBuilder } from "./constraintTypes";
+/**
+ * Creates a fresh unindexed constraint builder: the `q` a rule receives when it
+ * declares no `withIndex` (DD 13). Comparisons produce a `compare` node;
+ * `and`/`or`/`not` wrap the nodes their arguments produced, so a whole
+ * expression evaluates bottom-up into one tree.
+ *
+ * Unlike {@link createIndexConstraintBuilder} this takes **no sink and keeps no
+ * state**. The indexed builder records a flat sequence, so someone has to own the
+ * list; here the combinators consume values and return values, which means the
+ * callback's own return value already *is* the root of the tree. Two calls to this
+ * factory cannot interfere because there is nothing to interfere with — every node
+ * is freshly allocated and reachable only through what the caller was handed.
+ *
+ * The framework reads the result by reinterpreting the returned
+ * {@link ConstraintResult} as {@link AccessFilterConstraint} — the same erasure this
+ * module performs internally on combinator arguments. `ConstraintResult` is nominal
+ * precisely so a rule cannot hand back a hand-built object literal; only a real
+ * chain call can produce one.
+ *
+ * @typeParam TDoc - Document shape for the resource this rule governs.
+ * @returns A stateless builder. Every call returns an independent object, and
+ *   nothing is shared between them.
+ */
+export declare function createFilterConstraintBuilder<TDoc>(): FilterConstraintBuilder<TDoc>;
+//# sourceMappingURL=createFilterConstraintBuilder.d.ts.map

package/dist/access/createFilterConstraintBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFilterConstraintBuilder.d.ts","sourceRoot":"","sources":["../../src/access/createFilterConstraintBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,KAAK,uBAAuB,CAAC,IAAI,CAAC,CA6DnF"}

package/dist/access/createIndexConstraintBuilder.d.ts

@@ -0,0 +1,40 @@
+import type { AccessIndexConstraint, ConstraintBuilder, ConstraintResult } from "./constraintTypes";
+/**
+ * Creates a positional constraint builder — the `ix` a rule receives inside
+ * `q.withIndex(name, (ix) => …)`.
+ *
+ * **Pure.** Every method returns a NEW builder carrying the accumulated list; there
+ * is no shared array and no caller-owned sink. That is what makes "only the value
+ * the callback RETURNS counts" true rather than aspirational: a chain the rule
+ * builds and discards leaves nothing behind, exactly like any other dead expression.
+ * The earlier `{ into }` sink made discarded chains apply anyway, which surprised in
+ * the one direction that matters — a rule doing more than it appeared to.
+ *
+ * The TYPE narrows per call — {@link ConstraintBuilder}'s three-interface state
+ * machine only exposes the methods still legal at each position. The RUNTIME object
+ * does not: each node carries all five methods, cast to the narrowing type on
+ * return. Type safety is enforced entirely at the call site, never here.
+ *
+ * @typeParam TFields - The index's field tuple, in declaration order.
+ * @typeParam TDoc - The document shape constraint values are typed from.
+ * @returns A builder positioned at field 0, with nothing accumulated.
+ */
+export declare function createIndexConstraintBuilder<TFields extends readonly string[], TDoc>(): ConstraintBuilder<TFields, TDoc>;
+/**
+ * Reads the constraints a returned positional chain accumulated.
+ *
+ * The counterpart to the cast above: `ConstraintResult` is nominal and carries no
+ * public shape, so only this module can get the list back out. Called by
+ * `createAccessQueryBuilder` on whatever the range callback returned — which is why
+ * a discarded chain contributes nothing.
+ *
+ * @typeParam TDoc - The document shape constraint values are typed from.
+ * @param result - The value a range callback returned.
+ * @returns Its accumulated constraints, in call order. `[]` when `result` did not
+ *   come from this module — unreachable through the types, and treated as "no
+ *   constraints" rather than throwing, since `validateAccessConstraints` owns
+ *   diagnosing a rule that reached past them.
+ * @internal
+ */
+export declare function readIndexConstraints<TDoc>(result: ConstraintResult): readonly AccessIndexConstraint<string, TDoc>[];
+//# sourceMappingURL=createIndexConstraintBuilder.d.ts.map

package/dist/access/createIndexConstraintBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createIndexConstraintBuilder.d.ts","sourceRoot":"","sources":["../../src/access/createIndexConstraintBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAa3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,SAAS,SAAS,MAAM,EAAE,EACjC,IAAI,KACD,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,CA0CpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EACvC,MAAM,EAAE,gBAAgB,GACvB,SAAS,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAGhD"}

package/dist/access/hasPermission.d.ts

@@ -0,0 +1,85 @@
+import { PermissionScope } from "./constants";
+import type { PermissionCheck, SubjectEntry, VexAccessConfig } from "./types";
+/**
+ * Props required for the hasPermission({...}) function
+ *
+ * @param access - The resolved config from `defineAccess()`. `undefined`
+ *   disables access control entirely — every check passes.
+ * @param user - The authenticated user document. Roles are derived from
+ *   `user[access.userRolesField]` (`string` or `string[]`); a missing or empty
+ *   value falls back to access.anonRole
+ * @param organization - The organization document forwarded to callbacks.
+ *   Only surfaces when `access.orgCollectionSlug` is configured.
+ * @param resource - Subject name — a resource slug, a built-in subject
+ *   (e.g. `"adminPanel"`), or a custom resource name.
+ * @param action - Action on `resource`, typed per subject.
+ * @param data - Document/context forwarded to permission callbacks.
+ * @param throwOnDenied - When `true`, throws `VexAccessError` instead of
+ * @param scope Which question to answer when a role's check is a callback that
+ * needs the document and `data` was not supplied:
+ * `"all"` (default) asks "may they do this to every document" and resolves such
+ * a check to `false` — fail-closed, never throws; `"any"` asks "may they do this
+ * to at least one document" and resolves it to `true` (nav/sidebar/list gating —
+ * row-level filtering happens separately in `find`/`get`); `"doc"` demands an
+ * exact per-document answer and throws `VexAccessError` when `data` is missing,
+ * which is what you want in edit views. Has no effect on static boolean checks,
+ * and no effect when `data` is provided (the callback is always run against it).
+ * @default "all"
+ */
+export interface HasPermissionProps<TSubjects extends Record<string, SubjectEntry> = Record<string, SubjectEntry>, TSubject extends keyof TSubjects & string = keyof TSubjects & string, TData extends {} = {}> {
+    access?: VexAccessConfig<TSubjects>;
+    user: Record<string, unknown> | null;
+    organization?: Record<string, unknown>;
+    resource: TSubject;
+    action: TSubjects[TSubject]["action"];
+    data?: TData;
+    throwOnDenied?: boolean;
+    scope?: PermissionScope;
+}
+/**
+ * Resolves runtime role-based access for a single subject + action, merging
+ * every role the user holds into one decision.
+ *
+ * This is the single runtime entry point — every server API guard, admin panel
+ * gate, and custom-subject check calls it; the resolution helpers below are
+ * module-private.
+ *
+ * Resolution, per role, first hit wins: subject boolean shorthand → explicit
+ * action key → subject-level `WILDCARD_KEY` → role-level `WILDCARD_KEY`
+ * (undeclared subjects only) → `defaultPermissionMode`. Roles then OR-merge:
+ * any role allowing allows.
+ *
+ * @param props @see {@link HasPermissionProps}
+ * @returns `true` when the action is permitted for the caller.
+ * @throws {VexAccessError} When `throwOnDenied` is `true` and access is denied —
+ *   carries `resource` and `action`.
+ *
+ * @example
+ * ```ts
+ * hasPermission({ access, user, resource: "posts", action: "update" }); // boolean
+ * hasPermission({ access, user, resource: "posts", action: "delete",
+ *   data: post, throwOnDenied: true }); // throws VexAccessError on deny
+ * ```
+ */
+export declare function hasPermission<TSubjects extends Record<string, SubjectEntry>, TSubject extends keyof TSubjects & string, TData extends {}>(props: HasPermissionProps<TSubjects, TSubject, TData>): boolean;
+/**
+ * Resolves a single action's check from a per-action map, consulting the
+ * action-level wildcard when the explicit action isn't declared.
+ *
+ * The wildcard precedence lives in exactly one place so `hasPermission`,
+ * `resolveAccessIndex`, and any future evaluator (e.g. DB-backed roles) share
+ * it. Presence, not truthiness, decides: an explicit `false` still wins over
+ * the wildcard.
+ *
+ * @param props - Input props.
+ * @param props.resource - The per-action map declared for one role + resource.
+ * @param props.action - The action being resolved.
+ * @returns The declared check for `action`, else the wildcard's check, else
+ *   `undefined` (caller falls through to `defaultPermissionMode`).
+ * @internal
+ */
+export declare function resolveActionCheck(props: {
+    resource: Record<string, unknown>;
+    action: string;
+}): PermissionCheck | undefined;
+//# sourceMappingURL=hasPermission.d.ts.map

package/dist/access/hasPermission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasPermission.d.ts","sourceRoot":"","sources":["../../src/access/hasPermission.ts"],"names":[],"mappings":"AACA,OAAO,EAAuC,eAAe,EAAgB,MAAM,aAAa,CAAC;AAIjG,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,kBAAkB,CACjC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7E,QAAQ,SAAS,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,SAAS,GAAG,MAAM,EACpE,KAAK,SAAS,EAAE,GAAG,EAAE;IAErB,MAAM,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC9C,QAAQ,SAAS,MAAM,SAAS,GAAG,MAAM,EACzC,KAAK,SAAS,EAAE,EAChB,KAAK,EAAE,kBAAkB,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,OAAO,CAwEhE;AAmMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,eAAe,GAAG,SAAS,CAQ9B"}

package/dist/access/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./constants";
+export * from "./types";
+export * from "./config";
+export * from "./hasPermission";
+export * from "./canAccessAdminPanel";
+export * from "./resolveAccessRule";
+export * from "./pickQueryIndex";
+export * from "./constraintTypes";
+export * from "./createIndexConstraintBuilder";
+export * from "./createFilterConstraintBuilder";
+export * from "./createAccessQueryBuilder";
+export * from "./buildChecks";
+//# sourceMappingURL=index.d.ts.map

package/dist/access/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/access/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC"}

package/dist/access/pickQueryIndex.d.ts

@@ -0,0 +1,42 @@
+import type { IndexRangeFn, QueryIndex } from "./types";
+/**
+ * Chooses the single index a query will use, arbitrating between an
+ * access-contributed index and whatever the caller explicitly requested.
+ * Convex permits exactly one `withIndex` per query, so exactly one wins.
+ *
+ * 1. Caller's index wins the slot when it names a DIFFERENT index — usually a
+ *    highly selective lookup; the access `filter` still enforces the rule per
+ *    document (`hasPermission`), so this only ever costs reads, never
+ *    correctness.
+ * 2. Same name ⇒ ranges merge, so the compound constraint (access's prefix AND
+ *    the caller's continuation) is served by one query, no degradation.
+ * 3. Free slot (no caller index) ⇒ the access index claims it — the common
+ *    list-view case, where the view passes no index of its own.
+ *
+ * Never authorizes: whichever index wins, the access rule's `filter` runs per
+ * document. Arbitration decides how many rows get read, not which are allowed.
+ *
+ * @param props - Input props.
+ * @param props.accessIndex - `resolveAccessIndex`'s result for this query, if any.
+ * @param props.callerIndex - The index the caller explicitly requested, if any.
+ *   Its `range` is optional, mirroring `find`'s `withIndex` arg — a caller may
+ *   name an index purely to order results.
+ * @returns The index to apply, or `undefined` when neither side supplies one
+ *   (an un-narrowed scan, today's behavior).
+ *
+ * @example
+ * ```ts
+ * pickQueryIndex({
+ *   accessIndex: { name: "by_author", range: (q) => q.eq("authorId", "u1") },
+ * });
+ * // → { name: "by_author", range: … }  (free slot)
+ * ```
+ */
+export declare function pickQueryIndex(props: {
+    accessIndex?: QueryIndex;
+    callerIndex?: {
+        name: string;
+        range?: IndexRangeFn;
+    };
+}): QueryIndex | undefined;
+//# sourceMappingURL=pickQueryIndex.d.ts.map

package/dist/access/pickQueryIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pickQueryIndex.d.ts","sourceRoot":"","sources":["../../src/access/pickQueryIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAwExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;CACtD,GAAG,UAAU,GAAG,SAAS,CA4BzB"}