@rebasepro/common 0.19.1 → 0.19.2-canary.g08eed46

package/dist/collections/field-access.d.ts

@@ -0,0 +1,76 @@
+import type { CollectionConfig, FieldAccess, Property } from "@rebasepro/types";
+/**
+ * Field-level access control: one mechanism, read by every enforcement point.
+ *
+ * A collection's `securityRules` decide which *rows* a caller reaches;
+ * `property.access` decides which *fields* of a reached row they see and may
+ * set. The two are independent — a field rule never widens row access, and a
+ * row a caller cannot read has no fields to talk about.
+ *
+ * `excludeFromApi` is sugar for `access: { read: [], write: [] }` and is
+ * normalised into it by {@link effectiveAccess}, which is the only place either
+ * spelling is read. It used to be its own code path in five files — the read
+ * strip, the write refusal, the SDK generator, the OpenAPI schema builder and
+ * the filter-parameter builder — and the second rule would have made ten.
+ * There is one predicate now, and the flag is a shorthand for it.
+ *
+ * @module
+ */
+/**
+ * The caller a field rule is judged against: whatever the call context carries
+ * as the user's application roles.
+ *
+ * `undefined` is the trusted server plane — an in-process `rebase.data` call
+ * with no request behind it, the auth adapter writing a password hash, a
+ * migration. Every API boundary has a viewer: an unauthenticated REST request is
+ * scoped as `{ uid: ANONYMOUS_USER_ID, roles: ["anon"] }` before it reaches a
+ * driver, so "no viewer" cannot be reached from outside.
+ */
+export interface FieldViewer {
+    roles?: readonly string[];
+}
+/**
+ * The role that satisfies any non-empty list.
+ *
+ * The same arm every baseline policy carries: `security_rules` injects
+ * `rolesOverlap(['admin'])` into the default read and write policies, and
+ * `rebase.dataAsAdmin` is scoped with `{ uid: "service", roles: ["admin"] }`.
+ * Without this an author could declare `access: { read: ["hr"] }` and lock the
+ * administrator out of a column of their own database — and lock the Studio out
+ * of rendering it.
+ */
+export declare const ADMIN_ROLE = "admin";
+/**
+ * What a property's access rules actually are, with `excludeFromApi` expanded.
+ *
+ * Returns `undefined` when the property constrains nothing, so callers can skip
+ * the whole check for the overwhelmingly common case.
+ */
+export declare function effectiveAccess(property: Property | undefined): FieldAccess | undefined;
+/** May this caller receive this field's value? */
+export declare function canReadField(property: Property | undefined, viewer: FieldViewer | undefined): boolean;
+/** May this caller set this field's value? */
+export declare function canWriteField(property: Property | undefined, viewer: FieldViewer | undefined): boolean;
+/**
+ * The names on this collection a caller may not touch, in the two spellings a
+ * caller can write them in.
+ *
+ * `declared` is the property keys, which is what has to leave a *known-fields*
+ * set. `refused` is those plus the physical column names behind them: a caller
+ * who knows the table can send `password_hash` as readily as `passwordHash`, and
+ * a rule that only knew the wire name would be one rename away from useless.
+ *
+ * `kind` picks which half of the rule is read; nothing else differs.
+ */
+export declare function restrictedFieldNames(collection: CollectionConfig, viewer: FieldViewer | undefined, kind: "read" | "write"): {
+    declared: string[];
+    refused: Set<string>;
+};
+/**
+ * True when nothing on this collection restricts a field, for either direction.
+ *
+ * Every read of every row runs through the strip, so the collection that has no
+ * rules — which is almost all of them — has to cost one property walk and no
+ * allocation.
+ */
+export declare function hasFieldAccessRules(collection: CollectionConfig): boolean;

package/dist/collections/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./CollectionRegistry.js";
 export * from "./default-collections.js";
+export * from "./field-access.js";

package/dist/data/buildRebaseData.d.ts

@@ -1,4 +1,13 @@
 import { DataDriver, RebaseData, RebaseSdkData } from "@rebasepro/types";
+/**
+ * Derive the response key an aggregate comes back under.
+ *
+ * `sum(total)` → `sum_total`, `count()` → `count`. Written once, here, because
+ * the REST parser derives the same alias from `?select=sum(total)` and the two
+ * have to agree — a caller reading `row.sum_total` off an SDK result and off an
+ * HTTP response is reading the same key or the SDK is broken.
+ */
+export declare function aggregateAlias(fn: string, field?: string): string;
 export interface EntityDataOptions {
     /**
      * Look up a collection's config by slug, to derive row addresses from its
@@ -10,20 +19,10 @@ export interface EntityDataOptions {
      */
     resolveCollection?: (slug: string) => {
         properties?: Record<string, unknown>;
+        relations?: unknown[];
+        slug?: string;
     } | undefined;
 }
-/**
- * Build a `RebaseData` object from a `DataDriver` using JavaScript Proxy.
- *
- * This is the key bridge: any property access like `data.products` returns
- * a `CollectionAccessor` backed by the underlying DataDriver, without
- * needing per-collection code generation.
- *
- * @example
- * const data = buildRebaseData(driver);
- * await data.products.create({ name: "Camera", price: 299 });
- * const { data: items } = await data.products.find({ where: { status: ["==", "published"] } });
- */
 export declare function buildRebaseData(driver: DataDriver, options?: EntityDataOptions): RebaseData;
 /**
  * Wrap a flat {@link RebaseSdkData} into a Entity-shaped {@link RebaseData}.

package/dist/data/cursor.d.ts

@@ -0,0 +1,102 @@
+import type { OrderByTuple } from "@rebasepro/types";
+/**
+ * The keyset-cursor wire codec.
+ *
+ * ## Why this is one module
+ *
+ * Keyset pagination was implemented three times and reachable once. The driver
+ * has a NULL-correct multi-key comparison (`FetchService.buildKeysetComparison`)
+ * that only a WebSocket `startAfter` could reach; REST could not seek at all;
+ * and the SDK's `iterate({cursor})` re-implemented a *single*-column keyset as a
+ * `where` clause, which threw on any multi-key sort and silently dropped rows
+ * whose sort value was NULL. Three implementations, three answers to "what is
+ * page two".
+ *
+ * There is now one. The driver's comparison is the implementation; this module
+ * is the only thing that says how a cursor is written down, and every transport
+ * — the REST `?after=`, the WebSocket `startAfter`, the SDK's `iterate()` —
+ * carries the string this produces and hands it back unread.
+ *
+ * ## What a cursor holds
+ *
+ * The sort keys the query was ordered by, the last served row's value for each
+ * of them, and that row's id. The keys travel *with* the values because a
+ * cursor that carried only values would be silently reinterpretable: paging a
+ * `created_at DESC` listing and then asking for `title ASC` would seek on the
+ * dates as though they were titles. Carrying the keys makes that a refusal
+ * ({@link CursorMismatchError}) rather than a page of arbitrary rows.
+ *
+ * ## Opacity
+ *
+ * The encoding is base64url of JSON, and it is **not** API. It is opaque so it
+ * can change — adding a key, changing how a value is tagged — without every
+ * client that learned to read it breaking. Nothing outside this file parses it.
+ *
+ * @module
+ */
+/** The decoded contents of a cursor. */
+export interface DecodedCursor {
+    /** The sort keys the cursor was produced under, in order of significance. */
+    orderBy: OrderByTuple[];
+    /** The last served row's value for each sort key, by field name. */
+    values: Record<string, unknown>;
+    /** The last served row's id, which breaks ties on the last key. */
+    id: unknown;
+}
+/** A cursor that cannot be read at all — truncated, re-encoded, or invented. */
+export declare class CursorError extends Error {
+    readonly code = "INVALID_CURSOR";
+    constructor(detail: string);
+}
+/**
+ * A cursor that reads fine but describes a different query.
+ *
+ * Separate from {@link CursorError} because the fix is different: this one is
+ * not a corrupt string, it is a correct cursor used against a sort it was not
+ * produced under. Seeking anyway would return rows in an order nobody asked
+ * for, and — worse — would look like it worked.
+ */
+export declare class CursorMismatchError extends Error {
+    readonly code = "CURSOR_ORDER_MISMATCH";
+    constructor(cursorKeys: string[], queryKeys: string[]);
+}
+/**
+ * Encode "everything strictly after this row, in this order".
+ *
+ * @param orderBy the sort keys the listing ran under, in order of significance
+ * @param row     the last row served, which the next page picks up after
+ * @param id      that row's id — the tiebreaker every keyset comparison ends on
+ * @returns the opaque cursor, or `undefined` when no cursor can describe the
+ *   page. That is not a failure: a listing sorted by relevance has no stored
+ *   value to compare a later page against (scores are computed per query and
+ *   are not on the same scale between two of them), so it pages by offset and
+ *   `meta.nextCursor` is simply absent.
+ */
+export declare function encodeCursor(orderBy: OrderByTuple[] | undefined, row: Record<string, unknown>, id: unknown): string | undefined;
+/**
+ * Read a cursor produced by {@link encodeCursor}.
+ *
+ * @throws {CursorError} when the string is not a cursor this codec wrote.
+ */
+export declare function decodeCursor(raw: string): DecodedCursor;
+/**
+ * The `orderBy` a request should run under, given a cursor and whatever sort
+ * the request itself named.
+ *
+ * A request that names no sort **adopts the cursor's** — that is what makes
+ * `find({ after })` work without restating the `orderBy` from the previous
+ * call, and it cannot be wrong, since the cursor is the only sort in play.
+ * A request that names one must name the *same* one, key for key, direction for
+ * direction, nulls for nulls; anything else is {@link CursorMismatchError}.
+ *
+ * @throws {CursorMismatchError}
+ */
+export declare function reconcileCursorOrder(cursor: DecodedCursor, requested: OrderByTuple[] | undefined): OrderByTuple[];
+/**
+ * The `startAfter` shape the driver contract takes, built from a cursor.
+ *
+ * The driver has always accepted `{ id, values }`; this is the one place that
+ * shape is produced, so the REST route and the WebSocket ingress cannot drift
+ * into two spellings of the same seek.
+ */
+export declare function cursorToStartAfter(cursor: DecodedCursor): Record<string, unknown>;

package/dist/data/include-spec.d.ts

@@ -0,0 +1,128 @@
+import type { FilterValues, IncludeSpec, LogicalCondition, OrderByTuple } from "@rebasepro/types";
+/**
+ * The `include` codec: one shape, whatever spelling it arrived in.
+ *
+ * `include` reaches the driver by four routes — the REST `?include=` parameter,
+ * a WebSocket subscribe frame, the SDK's `include(...)`, and the admin panel's
+ * "all relations" — and each used to hand the driver something slightly
+ * different. This normalises all four to one tree, so the fetch pipeline has a
+ * single thing to read and `find()`, `findById()` and `listen()` cannot disagree
+ * about what "include the author" means.
+ *
+ * @module
+ */
+/**
+ * One relation to load, and how.
+ *
+ * `children` is the nesting: `comments.author` is a `comments` node with an
+ * `author` child. Every other field narrows the rows *of this relation* — the
+ * same knobs a top-level query has, which is the point.
+ */
+export interface IncludeNode {
+    /** Rows to load per parent row. */
+    limit?: number;
+    /** Filter over the related rows. */
+    where?: FilterValues<string>;
+    /** An `and`/`or`/`not` group over the related rows. */
+    logical?: LogicalCondition;
+    /** Sort for the related rows. */
+    orderBy?: OrderByTuple[];
+    /** Columns of the related row to return. */
+    fields?: string[];
+    /** Relations of the related row, loaded in turn. */
+    children: Record<string, IncludeNode>;
+}
+/**
+ * A whole `include` request: the tree, plus whether the caller asked for
+ * *every* relation.
+ *
+ * The wildcard is kept as a flag rather than expanded into names here, because
+ * expanding it needs the collection — which this package does not have. The
+ * driver expands it against the relations it actually resolved.
+ */
+export interface NormalizedInclude {
+    /** `include=*` — every relation of the collection, one hop deep. */
+    wildcard: boolean;
+    /** The named relations. Empty when `wildcard` is set alone. */
+    tree: Record<string, IncludeNode>;
+}
+/** An `include` that cannot be read, as opposed to one naming a relation that does not exist. */
+export declare class IncludeSpecError extends Error {
+    readonly code: string;
+    constructor(detail: string, code?: string);
+}
+/**
+ * Collapse any {@link IncludeSpec} spelling into one tree.
+ *
+ * `["author", "comments.author"]` and
+ * `{ author: true, comments: { include: { author: true } } }` normalize to the
+ * same value — which is the whole point: the REST parameter can only carry the
+ * flat spelling, the SDK prefers the tree, and the driver should never learn
+ * about either.
+ *
+ * @throws {IncludeSpecError} for a shape that is not an include at all, or one
+ *   that nests past {@link MAX_INCLUDE_DEPTH}.
+ */
+export declare function normalizeInclude(spec?: IncludeSpec): NormalizedInclude | undefined;
+/**
+ * Every relation name a tree names, as dotted paths — `["comments",
+ * "comments.author"]`.
+ *
+ * Used to report which names an `include` asked for when one of them is not a
+ * relation, and to serialize a tree that carries no per-relation options back
+ * to the flat wire spelling.
+ */
+export declare function includePaths(tree: Record<string, IncludeNode>, prefix?: string): string[];
+/**
+ * The relation names an `include` asks for at the top level.
+ *
+ * `["author", "comments.author"]` and `{author: true, comments: {...}}` both
+ * answer `["author", "comments"]` — a *hop*, not a path, because the only
+ * consumer is `?fields=`, which names keys on the row being returned and a
+ * nested relation is not one of those.
+ *
+ * Derived rather than passed: `include` has four spellings and three of them
+ * are not a `string[]`, so every consumer that wants the plain names either
+ * calls this or reimplements the flattening.
+ */
+export declare function topLevelIncludeNames(spec?: IncludeSpec): string[];
+/**
+ * Serialize an {@link IncludeSpec} for the REST `?include=` parameter.
+ *
+ * Two spellings, and which one is used is decided by the request rather than
+ * chosen:
+ *
+ * - **Comma-separated dotted paths** — `include=author,comments.author`. What a
+ *   plain include is, what a human types, and what every existing client sends.
+ * - **JSON**, when any relation carries options — `include={"comments":{"limit":5,
+ *   "include":{"author":true}}}`. The flat spelling has nowhere to put a
+ *   `limit`, and inventing a punctuation for it (`comments(limit:5)`) would be a
+ *   third grammar to learn beside the two this API already has.
+ *
+ * The server accepts both on every list and get route, and tells them apart the
+ * same way this does: a value starting with `{` is JSON.
+ */
+export declare function serializeInclude(spec?: IncludeSpec): string | undefined;
+/**
+ * A normalized tree, back in the {@link IncludeSpec} spelling a caller writes.
+ *
+ * The round trip is what lets a builder accumulate `include` calls: normalize
+ * each, merge, and hand the result back as a spec the next layer can normalize
+ * again. Idempotent, so doing it twice changes nothing.
+ */
+export declare function denormalizeInclude(normalized: NormalizedInclude): IncludeSpec;
+/**
+ * Combine several `include` requests into one.
+ *
+ * Repeated `.include(...)` calls on a query builder are additive: each names
+ * more of the graph to load, and a later one must not discard what an earlier
+ * one asked for. Assigning instead of merging is why `.include("author")
+ * .include("tags")` used to load only tags.
+ */
+export declare function mergeIncludeSpecs(existing: IncludeSpec | undefined, additions: (string | IncludeSpec)[]): IncludeSpec | undefined;
+/**
+ * Read the REST `?include=` parameter, in either spelling.
+ *
+ * @throws {IncludeSpecError} for malformed JSON or a tree that nests too deep.
+ */
+export declare function deserializeInclude(raw?: string): IncludeSpec | undefined;

package/dist/data/paginate.d.ts

@@ -26,12 +26,15 @@ export type PaginationErrorCode =
 "max-rows"
 /** The walk made its maximum number of requests without the server finishing. */
  | "max-pages"
-/** A cursor row carried no value for the cursor column. */
+/**
+ * The server said there was another page but issued no cursor to reach it.
+ *
+ * A query whose ordering has no stored value to seek on — relevance — is the
+ * case that produces this. Page it by offset instead.
+ */
  | "cursor-missing"
-/** Two consecutive pages ended on the same cursor value, so the walk cannot advance. */
- | "cursor-stalled"
-/** A `cursor` was asked for on one column while `orderBy` sorted by another. */
- | "cursor-order-mismatch";
+/** Two consecutive pages returned the same cursor, so the walk cannot advance. */
+ | "cursor-stalled";
 /**
  * Thrown when a walk stops for a reason the caller needs to know about.
  *

package/dist/data/query_builder.d.ts

@@ -1,6 +1,21 @@
 import { CollectionAccessor, FilterCondition, FindResponse, LogicalCondition, QueryBuilderInterface, WhereFilterOp, WhereValueFor, type ComputedSortField } from "@rebasepro/types";
 export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
+/**
+ * Negate a group: `not(a)` is `NOT a`, and `not(a, b)` is `NOT (a AND b)`.
+ *
+ * The conjunction, not the disjunction — one rule, stated on
+ * {@link LogicalCondition} and applied identically by the wire codec, the REST
+ * `?not=` parameter and every driver compiler. Groups nest, so De Morgan's
+ * other half is `not(or(a, b))`.
+ *
+ * It compiles to a real SQL `NOT (...)` rather than to inverted operators,
+ * which matters more than it looks: SQL is three-valued, so `NOT (a AND b)` and
+ * `(NOT a) OR (NOT b)` stop agreeing the moment a NULL is involved, and only
+ * one of them is the query the caller wrote. It also means a negation includes
+ * rows whose column is NULL — which is what `NOT` means.
+ */
+export declare function not(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition;
 export declare class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {
     private collection;

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export * from "./data/buildRoutedRebaseData.js";
 export * from "./data/resolveDataSource.js";
 export * from "./data/query_builder.js";
 export * from "./data/paginate.js";
+export * from "./data/cursor.js";
+export * from "./data/include-spec.js";
 export * from "./data/filter-conditions.js";
 export * from "./data/filter-dialect.js";
 export * from "./data/sort-dialect.js";