@rebasepro/common 0.22.0 → 0.24.0

package/dist/collections/CollectionRegistry.d.ts

@@ -24,6 +24,13 @@ export declare class CollectionRegistry {
     getGlobalCallbacks(): CollectionCallbacks | undefined;
     private collectionsByTableName;
     private collectionsBySlug;
+    /**
+     * Root collections whose driver stores them under a `path` other than
+     * their slug, by that path. A list, because the path is only unique within
+     * a data source: two collections in different databases may both be stored
+     * at `customer`.
+     */
+    private collectionsByDataPath;
     private rootCollections;
     private cachedCollectionsList;
     private rawCollectionsByTableName;
@@ -49,11 +56,61 @@ export declare class CollectionRegistry {
      */
     registerMultiple(collections: CollectionConfig[]): boolean;
     register(collection: CollectionConfig, rawCollection?: CollectionConfig): void;
+    /**
+     * Index a root collection by the path its driver stores it under, when
+     * that is not its slug. Only roots: a subcollection's `path` is relative to
+     * the record it hangs off, so it names nothing on its own.
+     */
+    private indexDataPath;
     private _registerRecursively;
     normalizeCollection(collection: CollectionConfig): CollectionConfig;
     private normalizeProperties;
     private normalizeProperty;
-    get(path: string): CollectionConfig | undefined;
+    /**
+     * The collection registered under `path`: by slug, by slug with hyphens
+     * for underscores, by table name, and last by the `path` a root Firestore
+     * or MongoDB collection declares for its driver.
+     *
+     * One string can name two collections. Declaring `slug: "fs_diagnosis",
+     * path: "diagnosis"` is how a Firestore collection sits beside a Postgres
+     * collection whose slug is `diagnosis` — and a reference read back from
+     * Firestore carries `diagnosis`. The order above settles it in favour of the
+     * slug unless `preferredDriver` is given: then the first collection whose
+     * data source or engine is `preferredDriver` wins. Pass a reference's
+     * `driver`, or the data source of the record the path was read from.
+     */
+    get(path: string, preferredDriver?: string): CollectionConfig | undefined;
+    /** Every collection {@link get} could answer `path` with, in its order. */
+    private candidatesFor;
+    /**
+     * The path a collection's rows are stored under, for the path the admin
+     * addresses it by.
+     *
+     * The admin addresses a collection by its slug — in routes, in
+     * `data.collection(...)`, in the `path` of every entity it lists — because
+     * the slug is what is unique. A Firestore or MongoDB collection may declare
+     * a `path` of its own ({@link getCollectionDataPath}), and its driver has to
+     * be handed that one, under every record and subcollection too:
+     * `fs_diagnosis/abc/locales` is stored at `diagnosis/abc/locales`.
+     *
+     * A path that names no registered collection, or runs only through
+     * collections stored under their slugs, comes back unchanged.
+     */
+    resolveDataPath(path: string): string;
+    /**
+     * The path the admin addresses a collection by, for a path its rows are
+     * stored under: the inverse of {@link resolveDataPath}, for a reference
+     * read back from its driver.
+     *
+     * The root is the longest leading run of segments naming a collection, and
+     * becomes its slug when the run is where that collection is stored. Each
+     * subcollection after a record id is matched by where it is stored too. A
+     * path that already names its collections by slug comes back unchanged.
+     *
+     * `preferredDriver` decides between a collection stored at the path and one
+     * whose slug it is, as in {@link get}.
+     */
+    resolveCollectionPath(path: string, preferredDriver?: string): string;
     /**
      * Gets the pristine, un-normalized collection exactly as it was provided.
      * Useful for the AST editor so it doesn't accidentally serialize injected metadata back to disk.
@@ -68,9 +125,21 @@ export declare class CollectionRegistry {
     getRawCollections(): CollectionConfig[];
     /**
      * Resolves a multi-segment path like "products/123/locales" and returns
-     * information about the collections and entity IDs along the path
+     * information about the collections and entity IDs along the path.
+     *
+     * A slug may contain slashes (`content/de-DE/podcasts`), so the root is
+     * the longest leading run of segments naming a registered collection, and
+     * each subcollection is matched the same way among its parent's.
+     *
+     * @param options.allowRecordPath accept a path that ends at a record
+     * (`…/{id}`) and resolve it to the collection holding that record, with the
+     * id last in `entityIds`. Without it such a path is an error. Only the
+     * registry can tell the two shapes apart, because only it knows where each
+     * slug ends.
      */
-    resolvePathToCollections(path: string): {
+    resolvePathToCollections(path: string, options?: {
+        allowRecordPath?: boolean;
+    }): {
         collections: CollectionConfig[];
         entityIds: (string | number)[];
         finalCollection: CollectionConfig;

package/dist/collections/default-collections.d.ts

@@ -17,8 +17,8 @@ export declare const defaultUsersCollection: import("@rebasepro/types").Postgres
 } & {
     id?: string | undefined;
     metadata?: import("@rebasepro/types").InferEntityType<{}> | undefined;
-    photoURL?: string | undefined;
     roles?: string[] | undefined;
+    photoURL?: string | undefined;
     passwordHash?: string | undefined;
     emailVerified?: boolean | undefined;
     emailVerificationToken?: string | undefined;

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

@@ -60,6 +60,11 @@ export declare function canWriteField(property: Property | undefined, viewer: Fi
  * 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.
  *
+ * A restricted to-one relation takes its foreign key with it. `bandId: 7` names
+ * the band exactly as `band: { id: 7 }` does, and the row carries the column
+ * beside the relation — so a rule on the relation that left the key alone
+ * withheld the value from the row and still let `?bandId=7` ask for it.
+ *
  * `kind` picks which half of the rule is read; nothing else differs.
  */
 export declare function restrictedFieldNames(collection: CollectionConfig, viewer: FieldViewer | undefined, kind: "read" | "write"): {

package/dist/collections/index.d.ts

@@ -3,3 +3,4 @@ export * from "./CollectionRegistry.js";
 export * from "./default-collections.js";
 export * from "./engine-support.js";
 export * from "./field-access.js";
+export * from "./soft-delete.js";

package/dist/collections/soft-delete.d.ts

@@ -0,0 +1,23 @@
+import type { CollectionConfig } from "@rebasepro/types";
+/** The field `softDelete: true` means, when the object form names none. */
+export declare const DEFAULT_SOFT_DELETE_FIELD = "deletedAt";
+/**
+ * The property a `softDelete` collection records a deletion in — its wire
+ * name, what a delete stamps and what a restore (an update to `null`) clears —
+ * or `undefined` for a collection without soft delete.
+ *
+ * One reading of the declaration for every layer that needs it: the driver
+ * that stamps and filters on it, and the REST route that has to recognise a
+ * restore before it looks the row up.
+ */
+export declare function softDeleteFieldOf(collection: CollectionConfig | undefined): string | undefined;
+/**
+ * Whether an update's values restore a soft-deleted row: they set the
+ * soft-delete field back to `null`, the documented restore.
+ *
+ * A restore is an ordinary update of a row every default read hides, so a door
+ * that looks the row up before updating it has to include the trashed rows for
+ * this update — and only for this one: any other edit of a trashed row is a
+ * 404.
+ */
+export declare function restoresSoftDeletedRow(collection: CollectionConfig | undefined, values: Record<string, unknown> | undefined): boolean;

package/dist/data/buildRebaseData.d.ts

@@ -22,6 +22,21 @@ export interface EntityDataOptions {
         relations?: unknown[];
         slug?: string;
     } | undefined;
+    /**
+     * Translate the path a collection is addressed by into the path its driver
+     * stores it under.
+     *
+     * The admin addresses every collection by its slug, and a Firestore or
+     * MongoDB collection may declare a `path` of its own: `fs_diagnosis` stored
+     * at `diagnosis`, and `fs_diagnosis/abc/locales` at `diagnosis/abc/locales`.
+     * Only the driver is handed the stored path. Rows keep the address they
+     * were asked for by, because that is what the admin resolves their
+     * collection, routes and deletes by.
+     *
+     * Late-bound, like `resolveCollection`. Absent, or answering `undefined`,
+     * the address is the stored path.
+     */
+    resolveDataPath?: (path: string) => string | undefined;
 }
 export declare function buildRebaseData(driver: DataDriver, options?: EntityDataOptions): RebaseData;
 /**

package/dist/data/cursor.d.ts

@@ -1,4 +1,4 @@
-import type { OrderByTuple } from "@rebasepro/types";
+import { type OrderByTuple } from "@rebasepro/types";
 /**
  * The keyset-cursor wire codec.
  *

package/dist/data/filter-dialect.d.ts

@@ -64,6 +64,19 @@ export declare class UnknownFilterOperatorError extends Error {
     };
     constructor(field: string, operator: string);
 }
+/**
+ * The query-parameter names a REST listing reads as something other than a
+ * field filter: pagination, sorting, includes, projection, search, the logical
+ * groups, the JSON `where` dialect, an aggregate's `select`/`groupBy`, and the
+ * soft-delete switches.
+ *
+ * One list for both ends. The server skips these names when it collects
+ * `?<field>=<op>.<value>` filters, and the SDK sends a filter on a column with
+ * one of these names inside `?where=` instead — a collection is free to have a
+ * `page`, `select` or `hard` column, and a filter on it sent as its own
+ * parameter was read as the parameter and never applied.
+ */
+export declare const RESERVED_QUERY_KEYS: ReadonlySet<string>;
 /**
  * Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
  * querystring record.