@vexcms/core 0.0.20 → 0.1.0-alpha.2

package/dist/access/resolveAccessRule.d.ts

@@ -0,0 +1,85 @@
+import type { AccessFilterFn, QueryIndex, SubjectEntry, VexAccessConfig } from "./types";
+/**
+ * Resolves the index an access rule contributes to a query, if any.
+ *
+ * Called once per query, before the Convex query is built. Answers a query-scoped
+ * question ("which index narrows this query?") rather than the document-scoped one
+ * `hasPermission` answers ("may they read this row?").
+ *
+ * **Never authorizes.** The per-document `hasPermission` pass still runs, so a
+ * missing or broader-than-necessary index can only cost reads — it can never admit
+ * a row a role does not permit. Failing to find an index is always safe; wrongly
+ * applying one is not, which is why every ambiguous case resolves to `undefined`
+ * (scan) rather than to a guess.
+ *
+ * Returns `undefined` when the single contributing rule used the FLAT algebra
+ * rather than calling `q.withIndex(…)`: there is a describable constraint, but no
+ * index to push it into. {@link resolveAccessConstraint} is the export that can
+ * still use it.
+ *
+ * @param props - Input props.
+ * @param props.access - Resolved access config; absent or `enabled: false` ⇒ no index.
+ * @param props.user - Caller, or `null` for anonymous (resolves through `access.anonRole`).
+ * @param props.organization - Active organization, forwarded to the rule's callback.
+ * @param props.resource - Subject slug (a collection or global slug).
+ * @param props.action - Query-shaped action (`"read"` | `"readDrafts"`).
+ * @returns The index to apply, or `undefined` to scan unnarrowed.
+ *
+ * @typeParam TSubjects - Resolved `SubjectMap`, inferred from `access`. Generic for
+ *   the same reason `HasPermissionProps` is: a concrete `SubjectMap<…>`
+ *   instantiation is not assignable to the erased
+ *   `VexAccessConfig<Record<string, SubjectEntry>>` default, because callback
+ *   contravariance makes instantiations mutually unassignable (P-002). Pinning the
+ *   default would reject every real `defineAccess()` result.
+ *
+ * @example
+ * ```ts
+ * const index = resolveAccessIndex({
+ *   access, user, resource: "pages", action: CRUD_ACTIONS.read,
+ * });
+ * // → { name: "by_author", range: (q) => q.eq("authorId", "u1") }
+ * ```
+ */
+export declare function resolveAccessIndex<TSubjects extends Record<string, SubjectEntry> = Record<string, SubjectEntry>>(props: {
+    access?: VexAccessConfig<TSubjects>;
+    user: Record<string, unknown> | null;
+    organization?: Record<string, unknown>;
+    resource: string;
+    action: string;
+}): QueryIndex | undefined;
+/**
+ * Resolves an access rule to a `.filter()` expression, if any.
+ *
+ * The sibling of {@link resolveAccessIndex}, for query shapes with no `withIndex`
+ * slot to claim (`search`) or where the caller's own index already claimed it
+ * (`find`'s displaced branch). Both share {@link selectSingleCondition}, so they
+ * cannot disagree about which rule applies.
+ *
+ * Succeeds for BOTH halves of a condition. An indexed rule's positional
+ * constraints compile to a filter expression just as well as they do to a range —
+ * the whole point of recording data rather than a callback — and a flat rule's tree
+ * compiles here too. When a condition carries both, they are `and`-ed.
+ *
+ * @param props - Input props.
+ * @param props.access - Resolved access config; absent or `enabled: false` ⇒ no filter.
+ * @param props.user - Caller, or `null` for anonymous (resolves through `access.anonRole`).
+ * @param props.organization - Active organization, forwarded to the rule's callback.
+ * @param props.resource - Subject slug.
+ * @param props.action - Query-shaped action.
+ * @param props.indexAlreadyApplied - Set when the caller already pushed this rule's
+ *   index range down via `.withIndex(name, range)`. The range is then omitted here,
+ *   leaving only the `filter` half — applying it twice would be redundant work on
+ *   every row. Leave unset (`find`'s displaced branch, `search`, `get`) to get the
+ *   whole condition as one expression.
+ * @returns A thunk taking the query's own `FilterBuilder`, or `undefined` when
+ *   nothing is left to exclude.
+ */
+export declare function resolveAccessConstraint<TSubjects extends Record<string, SubjectEntry> = Record<string, SubjectEntry>>(props: {
+    access?: VexAccessConfig<TSubjects>;
+    user: Record<string, unknown> | null;
+    organization?: Record<string, unknown>;
+    resource: string;
+    action: string;
+    indexAlreadyApplied?: boolean;
+}): AccessFilterFn | undefined;
+//# sourceMappingURL=resolveAccessRule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAccessRule.d.ts","sourceRoot":"","sources":["../../src/access/resolveAccessRule.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,cAAc,EAEd,UAAU,EACV,YAAY,EACZ,eAAe,EAChB,MAAM,SAAS,CAAC;AA8LjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7E,KAAK,EAAE;IACP,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,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,UAAU,GAAG,SAAS,CAkBzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7E,KAAK,EAAE;IACP,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,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,cAAc,GAAG,SAAS,CAwC7B"}