@rebasepro/types 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/controllers/data_driver.d.ts

@@ -21,10 +21,25 @@ export interface FetchOneProps<M extends Record<string, unknown> = Record<string
      */
     withDeleted?: boolean | "only";
 }
+/**
+ * What a row listener subscribes to: the row, and the relations each frame
+ * loads into it.
+ *
+ * @internal
+ */
+export type ListenOneTarget<M extends Record<string, unknown> = Record<string, unknown>> = FetchOneProps<M> & {
+    /**
+     * Relations to load into every frame, as {@link FetchCollectionProps.include}
+     * loads them into each row of a list. Without it a to-many relation
+     * is absent from each frame, and the admin's record form, opened by
+     * URL, showed it empty — so a save from it unlinked every related row.
+     */
+    include?: IncludeSpec;
+};
 /**
  * @internal
  */
-export type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> = FetchOneProps<M> & {
+export type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> = ListenOneTarget<M> & {
     onUpdate: (row: Record<string, unknown> | null) => void;
     onError?: (error: Error) => void;
 };
@@ -172,6 +187,13 @@ export type ListenCollectionProps<M extends Record<string, unknown> = Record<str
      * the two spellings then disagreed about what a page was.
      */
     page?: number;
+    /**
+     * Subscribe to the count alone: the server reads no rows, and each
+     * frame carries `rows: []` and `meta.total`. A server that predates it
+     * ignores the key and answers with the rows asked for (so ask for
+     * `limit: 1`) and the same `meta`. See `listenCount`.
+     */
+    countOnly?: boolean;
     onUpdate: (rows: Record<string, unknown>[], meta?: CollectionUpdateMeta) => void;
     onError?: (error: Error) => void;
 };
@@ -211,6 +233,39 @@ export interface SaveProps<M extends Record<string, unknown> = Record<string, un
      * targets rather than a 500 naming a constraint the caller never wrote.
      */
     onConflict?: readonly string[];
+    /**
+     * A check on the stored row an update addresses, run by the driver inside
+     * the write's own transaction, before any hook runs and before anything is
+     * written. See {@link RowPrecondition}. Honoured only by a driver that
+     * declares {@link DataDriver.checksRowPreconditions}; ignored on a create.
+     */
+    precondition?: RowPrecondition;
+}
+/**
+ * A check a caller makes on the row a write addresses, inside that write.
+ *
+ * The REST routes used to read the row in a transaction of their own before
+ * writing it, to answer a missing row with their 404 and to compare
+ * `If-Match`. Two transactions: the read loaded every declared relation of the
+ * row, and two writes carrying the same tag could both pass the comparison,
+ * because neither saw the other's write before making its own.
+ *
+ * @internal
+ */
+export interface RowPrecondition {
+    /**
+     * Lock the row before it is read, so no other write to it can land between
+     * this check and this write. A conditional write (`If-Match`) sets it; a
+     * plain existence check does not need it and does not pay for it.
+     */
+    lock?: boolean;
+    /**
+     * Judge the row as this caller reads it at the address written (their
+     * policies, their `beforeQuery`, the trash hidden unless the write is a
+     * restore or a purge) — `undefined` when there is none. Throw to refuse the
+     * write; nothing has been written when this runs.
+     */
+    check(stored: Record<string, unknown> | undefined): void | Promise<void>;
 }
 /**
  * @internal
@@ -277,6 +332,12 @@ export interface DeleteProps<M extends Record<string, unknown> = Record<string,
      * already this one.
      */
     hard?: boolean;
+    /**
+     * A check on the stored row, inside the delete's own transaction, before
+     * any hook runs. See {@link RowPrecondition}. Honoured only by a driver
+     * that declares {@link DataDriver.checksRowPreconditions}.
+     */
+    precondition?: RowPrecondition;
 }
 /**
  * @internal
@@ -517,6 +578,21 @@ export interface DataDriver {
      * Count the number of entities in a collection
      */
     count?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
+    /**
+     * Run several reads as one: `work` is handed a driver whose reads all go
+     * through a single read-only transaction that reads one snapshot, under
+     * this driver's identity and row-level security, and its result is
+     * returned.
+     *
+     * A list page is a read and a count, and each was a transaction of its
+     * own — the second checkout, `BEGIN`, identity setup and `COMMIT` cost as
+     * many round trips as the count itself. On one snapshot the two also
+     * agree: `meta.total` describes the rows the page was taken from, and an
+     * `ETag` the row the body was rendered from.
+     *
+     * Optional: a driver without it is called directly, read by read.
+     */
+    readTogether?<T>(work: (driver: DataDriver) => Promise<T>): Promise<T>;
     /**
      * Check if the given filter combination is valid
      * @param props
@@ -548,6 +624,14 @@ export interface DataDriver {
      * `fetchCollection` pipeline, enabling include-aware eager-loading.
      */
     restFetchService?: RestFetchService;
+    /**
+     * This driver reads the row an update or a delete addresses inside that
+     * write's own transaction, and runs {@link SaveProps.precondition} /
+     * {@link DeleteProps.precondition} on it there. A caller may then leave its
+     * own read of the row out. A driver without it ignores the precondition,
+     * so a caller must read the row itself.
+     */
+    readonly checksRowPreconditions?: boolean;
     /**
      * Return the admin capabilities of this driver.
      * @see SQLAdmin

package/dist/controllers/index.d.ts

@@ -4,5 +4,6 @@ export * from "./data.js";
 export * from "./data_driver.js";
 export * from "./effective_role.js";
 export * from "./storage.js";
+export * from "./storage-references.js";
 export * from "./email.js";
 export * from "./client.js";

package/dist/controllers/storage-references.d.ts

@@ -0,0 +1,114 @@
+import type { StorageSource } from "./storage.js";
+/**
+ * The scheme of a **storage reference**: a stored object named inside text.
+ *
+ * Text that embeds a file — a markdown body above all — cannot hold a private
+ * object's URL: that URL carries a download token which expires in minutes,
+ * after which every reader of the text gets a 401 for an image that is still in
+ * the bucket. It holds a reference instead,
+ * `rebase-storage:posts/cover.png` (`?storageId=media` for a named source),
+ * and whoever renders the text exchanges each reference for a fresh URL with
+ * {@link resolveStorageReferences} — `resolveStorageReferences(text, client)`
+ * from `@rebasepro/client` on a site.
+ *
+ * @group Models
+ */
+export declare const STORAGE_REFERENCE_SCHEME = "rebase-storage:";
+/**
+ * The object a storage reference names.
+ *
+ * @group Models
+ */
+export interface StorageReferenceTarget {
+    /** The object's key in its storage source. */
+    key: string;
+    /** The named storage source holding it. Absent for the default source. */
+    storageId?: string;
+}
+/**
+ * The reference for an object — what text stores in place of its URL.
+ *
+ * Every part is percent-encoded, so the reference contains no space,
+ * parenthesis or quote and survives as one markdown link destination whatever
+ * the file was called.
+ *
+ * @group Models
+ */
+export declare function storageReference(key: string, storageId?: string | null): string;
+/**
+ * Whether a string — an image's `src`, a link's `href` — is a storage reference.
+ *
+ * @group Models
+ */
+export declare function isStorageReference(value: string | null | undefined): value is string;
+/**
+ * The object a storage reference names, or `null` for anything else — a URL, a
+ * bare key, or a reference whose key would climb out of its prefix.
+ *
+ * @group Models
+ */
+export declare function parseStorageReference(value: string | null | undefined): StorageReferenceTarget | null;
+/**
+ * The object a private file's download URL was minted for, or `null` for any
+ * other URL.
+ *
+ * Text written before storage references stored such URLs —
+ * `…/storage/file/posts/cover.png?token=…` — and their tokens expired minutes
+ * later. The token still names the object it was minted for, so the URL can be
+ * traded for a fresh one, or for a reference. Read without verifying the
+ * token: it grants nothing here, it only says which object is meant, and the
+ * key in the URL must agree with it. Host-agnostic, since a URL written
+ * through one origin may be read through another.
+ *
+ * @group Models
+ */
+export declare function storageTargetOfDownloadUrl(url: string): StorageReferenceTarget | null;
+/**
+ * Every object `text` names: its storage references, and the private files'
+ * download URLs saved in it before references existed. An object named more
+ * than once may be listed more than once.
+ *
+ * @group Models
+ */
+export declare function storageTargetsInText(text: string): StorageReferenceTarget[];
+/**
+ * `text` with every private file's download URL replaced by the storage
+ * reference for its object — for rewriting text saved before references, so
+ * it stores what new text stores. Any other URL is left as it is.
+ *
+ * @group Models
+ */
+export declare function storageReferencesForDownloadUrls(text: string): string;
+/**
+ * Where {@link resolveStorageReferences} gets URLs from: a function that
+ * answers one, or anything shaped like a Rebase client — its `storage` for the
+ * default source and `createStorageSource(id)` for a named one.
+ *
+ * @group Models
+ */
+export type StorageReferenceResolver = ((target: StorageReferenceTarget) => Promise<string | null | undefined>) | {
+    storage?: StorageSource;
+    createStorageSource?(storageId: string): StorageSource;
+};
+/**
+ * Exchange every storage reference in `text` for a URL, at the moment the text
+ * is rendered.
+ *
+ * ```ts
+ * const html = markdown.render(await resolveStorageReferences(post.body, client));
+ * ```
+ *
+ * Each distinct object is asked for once — `getSignedUrl(key)` on its source —
+ * so a private object gets a freshly minted download URL every time the text is
+ * rendered. A reference that cannot be resolved (no such object, an unknown
+ * source) is left as it was, so a missing object reads as a missing image
+ * rather than as a failed render.
+ *
+ * A private file's download URL saved in the text before references existed
+ * is renewed the same way: its expired token still names the object (see
+ * {@link storageTargetOfDownloadUrl}). One that cannot be resolved is left as
+ * it was.
+ *
+ * @group Models
+ */
+export declare function resolveStorageReferences(text: string, from: StorageReferenceResolver): Promise<string>;

package/dist/controllers/storage.d.ts

@@ -8,13 +8,58 @@
  */
 export declare const PUBLIC_STORAGE_PREFIX = "public/";
 /**
- * True when a storage key/path points at a public object (lives under
- * {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the
- * bucket* — strip any `bucket/` and `scheme://` prefixes first.
+ * True when a storage **key** is public: it lies under
+ * {@link PUBLIC_STORAGE_PREFIX}.
+ *
+ * The key is read exactly as it is — the canonical key within its bucket, the
+ * one the server stores, serves, and hands a `storageAuthorize` hook as
+ * `key` — and nothing is parsed out of it. That is the difference from
+ * {@link isPublicStoragePath}, which reads a client-side *path* and so strips
+ * a `scheme://` and a leading `default/` bucket segment first. On a key both are
+ * wrong: `default/public/x` is a key in a folder called `default`, and a
+ * request path `notes://public/x` names the key `notes:/public/x`. Neither is
+ * public, and the server decides on this function so that it never says they
+ * are.
+ *
+ * @group Models
+ */
+export declare function isPublicStorageKey(key: string | null | undefined): boolean;
+/**
+ * True when a storage key or client-side path points at a public object
+ * (lives under {@link PUBLIC_STORAGE_PREFIX}).
+ *
+ * For a path as a client holds it: a `scheme://` prefix and a single leading
+ * `default/` bucket segment are stripped first. The server and a
+ * `storageAuthorize` hook, which hold the canonical key, use
+ * {@link isPublicStorageKey}.
  *
  * @group Models
  */
 export declare function isPublicStoragePath(path: string | null | undefined): boolean;
+/**
+ * The path the storage routes address an object by, from a key or from the
+ * `storageUrl` an upload returned (`<scheme>://<bucket>/<key>`, which is what a
+ * property with `includeBucketUrl: true` keeps in its column).
+ *
+ * The routes address a source's objects by key. On S3 and GCS the bucket in a
+ * `storageUrl` is always the source's own — the server refuses any other — so
+ * it is dropped: sent along, `s3://acme-media/products/a.png` reached the
+ * server as the key `acme-media/products/a.png`, the preview found nothing and
+ * a delete reported success while the object stayed. It worked on local disk
+ * only, because `local://default/<key>` happens to carry the one bucket
+ * segment the routes recognise — which is kept, as is any other local bucket.
+ *
+ * A bare key whose first folder is `default` is sent behind that bucket
+ * segment. The routes read one leading `default/` (in any case) as the bucket,
+ * so the key `default/photo.png` sent as it is names the root `photo.png`:
+ * {@link defaultBucketPath} is the spelling that names the key itself.
+ *
+ * Shared by every storage source that talks to those routes, so they address
+ * an object alike.
+ *
+ * @group Models
+ */
+export declare function storageObjectPath(keyOrUrl: string, bucket?: string): string;
 /**
  * @group Models
  */
@@ -35,18 +80,15 @@ export interface UploadFileProps {
      * and the property path within it (`coverImage`, `meta.avatar`,
      * `gallery` for an array of files).
      *
-     * The server reads it to enforce that property's own `storage.maxSize` and
-     * `storage.acceptedFiles`, which were declared per property, published in
-     * the generated types, rendered by the panel's file picker, and until now
-     * enforced by nothing on the server — so a `curl` past the picker put a
-     * 40 MB executable in a bucket whose config said "images, under 200 KB".
+     * The server holds the upload to that property's own `storage.maxSize`
+     * and `storage.acceptedFiles`. It holds every upload to the limits of the
+     * properties whose `storagePath` its key falls in anyway, named or not;
+     * naming the property adds that property's rule, which matters for a
+     * property whose `storagePath` is a function the server cannot read.
      *
      * Advisory in one direction only. The rules are resolved from the server's
-     * own registry by slug, so naming a property can make an upload *stricter*
-     * or leave it at the global cap; it can never widen anything.
-     *
-     * Omitted, the upload is checked against the deployment's global
-     * `maxFileSize` exactly as before.
+     * own registry by slug, so naming a property can make an upload *stricter*;
+     * it can never widen anything.
      */
     context?: UploadPropertyContext;
 }
@@ -237,4 +279,22 @@ export declare interface StorageReference {
      * this reference is the root.
      */
     parent: StorageReference | null;
+    /**
+     * The object's size in bytes, as the listing read it. Set on the objects
+     * of a listing from the built-in local, S3 and GCS sources; absent on
+     * folders and from a source that cannot list it without a request per
+     * object. Since 0.24.
+     */
+    size?: number;
+    /**
+     * When the object was last written, as an ISO 8601 timestamp — set where
+     * {@link size} is.
+     */
+    updated?: string;
+    /**
+     * The object's stored content type, as the listing read it: set by local
+     * storage and GCS. An S3 listing does not carry it, so on S3 it is absent
+     * and `getSignedUrl()` (or the metadata route) still says.
+     */
+    contentType?: string;
 }

package/dist/errors.d.ts

@@ -23,7 +23,21 @@
  *
  * @group Errors
  */
-export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "NETWORK_ERROR" | "OFFLINE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT" | (string & {});
+export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "NETWORK_ERROR" | "OFFLINE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT"
+/**
+ * Realtime: the socket closed after a request was written and before the
+ * server answered — the request may or may not have run, and it is never
+ * re-sent. On a live subscription's `onError`: the connection has been
+ * down longer than a blip; the subscription is kept and resumes, with a
+ * fresh `onUpdate`, when the socket is back.
+ */
+ | "CONNECTION_LOST"
+/**
+ * Realtime: no answer within the request timeout of the call — either it
+ * waited for a socket the whole time and was never sent, or it was written
+ * and never answered.
+ */
+ | "REQUEST_TIMEOUT" | (string & {});
 /**
  * Structured initializer for {@link RebaseApiError}.
  *