@rebasepro/types 0.17.3 → 0.18.1

package/dist/types/admin_block.d.ts

@@ -29,7 +29,7 @@
  *
  * @group Models
  */
-export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "customViews", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "display", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromEntityViews", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort"];
+export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "browserCallbacks", "components", "customViews", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "display", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromEntityViews", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort"];
 /** A key of a collection's `admin` block. @group Models */
 export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
 /**
@@ -49,7 +49,7 @@ export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
  *
  * @group Models
  */
-export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "Filter", "filterOperators", "fixedFilter", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "sortable", "span", "spreadChildren", "urlPreview", "widget"];
+export declare const ADMIN_PROPERTY_KEYS: readonly ["canAddElements", "clearable", "columnWidth", "customProps", "disabled", "expanded", "Field", "Filter", "filterOperators", "fixedFilter", "format", "hideFromCollection", "includeEntityLink", "includeId", "markdown", "minimalistView", "multiline", "Preview", "previewAsTag", "previewProperties", "readOnly", "renderInForm", "sortable", "span", "spreadChildren", "urlPreview", "widget"];
 /** A key of a property's `admin` block. @group Models */
 export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
 /**

package/dist/types/auth_adapter.d.ts

@@ -29,7 +29,30 @@
  *
  * @group Auth
  */
-import type { Hono } from "hono";
+/**
+ * A sub-app an adapter hands back for the framework to mount.
+ *
+ * Structural on purpose. This was `Hono<any, any, any>`, and that one
+ * `import type { Hono } from "hono"` was the whole reason `@rebasepro/types`
+ * peer-depended on hono — which npm and pnpm auto-install, so **every browser
+ * app that installed `@rebasepro/client` got a 2.8 MB server framework in its
+ * lockfile and its security scanners**, for a type used by two optional methods
+ * that a browser app can never call.
+ *
+ * The shape is the same duck-type the function loader already validates at
+ * runtime (`isHonoLike`: a `fetch` method and a `routes` array), and a real
+ * `Hono` satisfies it — asserted in `auth_adapter.test.ts`, which does import
+ * hono, because a structural type is only worth having if something proves the
+ * real thing still fits.
+ *
+ * @group Auth
+ */
+export interface MountableRouter {
+    /** Handle a request. Hono, Elysia and a hand-rolled router all have this. */
+    fetch: (request: Request) => Response | Promise<Response>;
+    /** The routes the sub-app declares. Only its presence is contractual. */
+    routes: readonly unknown[];
+}
 /**
  * The normalized user object returned by `AuthAdapter.verifyRequest()`.
  *
@@ -51,6 +74,18 @@ export interface AuthenticatedUser {
     roles: string[];
     /** Whether the user has admin privileges. */
     isAdmin: boolean;
+    /**
+     * Whether this session is a GUEST — anonymous sign-in rather than an
+     * account.
+     *
+     * Optional, and absent means "not a guest", so an external adapter that
+     * has no such concept keeps behaving exactly as it did. When present it
+     * reaches the database as `rebase.is_anonymous()`, which is what lets a
+     * policy say "a signed-in person, not somebody who pressed Continue as
+     * guest" — two things that were the same principal inside every rule,
+     * because anonymous sign-in mints a real user row with a real uid.
+     */
+    isAnonymous?: boolean;
     /** Raw bearer token from the request (for forwarding). */
     rawToken?: string;
     /** Extra claims/metadata from the auth provider. */
@@ -363,19 +398,19 @@ export interface AuthAdapter {
      * - External adapter: typically returns `undefined` (auth is handled externally).
      * - Custom adapter: user mounts their own routes.
      *
-     * The return type uses `Hono<any, any, any>` because this sub-app will be
-     * mounted into a parent app via `.route()`, which accepts any Hono env type.
-     * Adapter implementations are free to use their own env (e.g. `Hono<HonoEnv>`).
+     * The return type is the structural {@link MountableRouter} rather than
+     * `Hono`, so this package needs no hono dependency. A real `Hono<HonoEnv>`
+     * satisfies it, and implementations are free to use their own env.
      *
      * @returns A Hono sub-app with auth routes, or `undefined` to skip route mounting.
      */
-    createAuthRoutes?(): Hono<any, any, any> | undefined;
+    createAuthRoutes?(): MountableRouter | undefined;
     /**
      * Mount admin routes (e.g. password reset for users).
      *
      * @returns A Hono sub-app with admin routes, or `undefined` to skip.
      */
-    createAdminRoutes?(): Hono<any, any, any> | undefined;
+    createAdminRoutes?(): MountableRouter | undefined;
     /**
      * Advertise what this auth adapter supports.
      *

package/dist/types/backend.d.ts

@@ -637,6 +637,27 @@ export interface BackendBootstrapper {
      * Return admin capabilities for this driver.
      */
     getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
+    /**
+     * Ask the database whether it is there, before anything else touches it.
+     *
+     * Boot's first database call is not `initializeDriver` — it is the schema
+     * provisioning that runs ahead of it, and a driver's connection diagnosis
+     * therefore never got the chance to run. A stopped database produced
+     * `Failed query: [redacted]` and a stack through drizzle internals: no host,
+     * no port, no `ECONNREFUSED`, and no hint about starting the thing.
+     *
+     * Implementations MUST issue the cheapest round trip they have (`SELECT 1`),
+     * MUST throw an error whose message names the host, the port and the
+     * driver's own reason, and MAY log a fuller diagnosis first. They MUST NOT
+     * throw for a reachable database that merely answered something unexpected —
+     * the caller treats a throw as fatal.
+     *
+     * `driverResult` is optional for the same reason as
+     * {@link ensureCollectionSchema}: this runs before `initializeDriver`, so an
+     * adapter that was constructed with its own connection has to fall back to
+     * it.
+     */
+    verifyConnection?(driverResult?: InitializedDriver): Promise<void>;
     /**
      * Bring the database's collection tables up to date, additively.
      *
@@ -680,6 +701,33 @@ export interface BackendBootstrapper {
     ensureCollectionPolicies?(collections: unknown[], driverResult?: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
+    /**
+     * Create the RLS helper functions on this source's database. See
+     * `DatabaseAdapter.ensureRlsRuntime`; needed on every source that is not
+     * the default, whose helpers arrive with the auth tables.
+     */
+    ensureRlsRuntime?(driverResult?: InitializedDriver): Promise<void>;
+    /**
+     * Re-check, after the schema exists, that requests will actually be
+     * constrained by the database's own authorization.
+     *
+     * A driver that isolates user requests by switching to a restricted role has
+     * to decide at connect time whether the switch is needed — and on a fresh
+     * database that question is asked before there is anything to answer with.
+     * The process then creates the schema, becomes its owner, and an owner is
+     * exempt from the policies on what it owns. So the answer that was true when
+     * the driver initialized can be false by the time it serves a request.
+     *
+     * This is where a driver asks again. It runs once, after collection tables,
+     * auth tables and policies are all in place, and it MUST fail rather than
+     * serve when the answer changed and cannot be acted on: booting anyway
+     * produces exactly the unenforced server this exists to prevent.
+     *
+     * Optional, because it is only meaningful for drivers whose isolation
+     * depends on state the schema affects. A driver with nothing to re-check
+     * omits it.
+     */
+    finalizeSecurityPosture?(driverResult: InitializedDriver): Promise<void>;
     /**
      * Read the collections schema version this database was last provisioned
      * from, or `null` when nothing has ever stamped it.

package/dist/types/collections.d.ts

@@ -76,6 +76,15 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      *
      * // A direct-transport Firestore data source registered as "analytics"
      * { slug: "events", dataSource: "analytics" }
+     *
+     * // The same, spelled once — `defineCollection` accepts the handle
+     * // `database("analytics")` returned and records its key here.
+     * import { analytics } from "../resources";
+     * defineCollection({ slug: "events", dataSource: analytics, … })
+     *
+     * A string on the recorded collection, because a collection is data past
+     * `defineCollection`: it serialises, it compares with `===`, and it reaches
+     * the admin UI over the wire, none of which a handle survives.
      */
     dataSource?: string;
     /**
@@ -188,8 +197,23 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
     engine?: "postgres" | undefined;
     /**
      * The PostgreSQL table name for this collection.
+     *
+     * Optional: it defaults to `toSnakeCase(slug)`, which is what
+     * `getTableName()` has always returned when it was absent. The type simply
+     * demanded what the runtime already derived, so the smallest collection
+     * anyone could write named its table twice —
+     * `{ slug: "todos", table: "todos", … }` — and "why do I write it twice"
+     * is the first question every evaluator asked.
+     *
+     * Set it only when the table name differs from the slug: an existing
+     * database whose table is `blog_posts` while the URL should stay `posts`.
+     *
+     * Note that a **derived** name is still a real name, and nothing yet warns
+     * when one moves. Foreign-key and junction column defaults are derived from
+     * the *slug* rather than from this field, so renaming a slug re-derives
+     * them on the next `db push` even where `table` is pinned.
      */
-    table: string;
+    table?: string;
     /**
      * The PostgreSQL schema name for this table.
      * E.g. "public", "rebase", "auth".

package/dist/types/cron.d.ts

@@ -12,6 +12,16 @@ import type { RebaseServerClient } from "../controllers/client.js";
  */
 export interface CronJobDefinition {
     schedule: string;
+    /**
+     * IANA time zone the schedule is read in, e.g. `"Europe/Madrid"`.
+     *
+     * Without it the expression is read in the process's own zone — UTC in
+     * nearly every container, the developer's own on a laptop — so `0 3 * * *`
+     * fires at a different wall-clock hour either side of a deploy. Name the
+     * zone and the schedule means one thing everywhere it runs. An unknown zone
+     * is refused when the job loads rather than silently read as local time.
+     */
+    timezone?: string;
     /** Human-readable name shown in the Studio UI. */
     name: string;
     /** Optional description shown in the Studio UI. */
@@ -74,6 +84,30 @@ export interface CronJobContext {
     scheduledAt: Date;
     /** A simple logger scoped to this job run. */
     log: (...args: unknown[]) => void;
+    /**
+     * Aborted when the run exceeds `timeoutSeconds`.
+     *
+     * The timeout has always stopped the scheduler *waiting* — it loses the
+     * race and the run is recorded as failed. It has never stopped the handler:
+     * a `fetch` to an unresponsive host kept its socket, and a job on a
+     * five-minute schedule with a five-minute timeout accumulated one abandoned
+     * request per tick until the process ran out of sockets, all of it invisible
+     * because the run was already marked failed.
+     *
+     * Pass it to anything that takes one, and the work stops when the run does:
+     *
+     * @example
+     * export default defineCron({
+     *     name: "Sync inventory",
+     *     schedule: "*\/15 * * * *",
+     *     timeoutSeconds: 60,
+     *     async handler({ signal, log }) {
+     *         const res = await fetch("https://supplier.example.com/stock", { signal });
+     *         log(`fetched ${res.status}`);
+     *     }
+     * });
+     */
+    signal: AbortSignal;
     /**
      * The server-side Rebase singleton — the **same object** `import { rebase }
      * from "@rebasepro/server"` returns, and the same one `defineFunction`

package/dist/types/database_adapter.d.ts

@@ -75,6 +75,16 @@ export interface DatabaseAdapter {
      * accepted every client as already authenticated.
      */
     initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown, adapter?: import("./auth_adapter.js").AuthAdapter): Promise<void> | void;
+    /**
+     * Ask the database whether it is there, before boot's first real query. See
+     * `BackendBootstrapper.verifyConnection` for the contract.
+     *
+     * Same forwarding requirement as the hooks below, and the symptom of
+     * dropping it is the failure this hook exists to prevent: a stopped database
+     * reported as `Failed query: [redacted]` and a stack through drizzle
+     * internals, naming no host, no port and no reason.
+     */
+    verifyConnection?(driverResult?: InitializedDriver): Promise<void>;
     /**
      * Bring the database's collection tables up to date, additively — the boot
      * companion to `db push`. See `BackendBootstrapper.ensureCollectionSchema`
@@ -109,6 +119,28 @@ export interface DatabaseAdapter {
     ensureCollectionPolicies?(collections: unknown[], driverResult?: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
+    /**
+     * Create the helper functions the generated policies call (`rebase.uid()`,
+     * `rebase.roles()` and their siblings) on THIS source's database.
+     *
+     * On the default source these arrive with the auth tables, because auth
+     * lives there. A second database gets no auth tables and had no helpers
+     * either, so every policy on it failed to create and every user read was
+     * denied — a collection declared on `database("analytics")` answered 401 on
+     * a healthy-looking backend. Idempotent; runs before
+     * `ensureCollectionPolicies` on every non-default source.
+     */
+    ensureRlsRuntime?(driverResult?: InitializedDriver): Promise<void>;
+    /**
+     * Re-check, once the schema exists, that requests will really be constrained
+     * by the database's own authorization. See
+     * `BackendBootstrapper.finalizeSecurityPosture`.
+     *
+     * Same forwarding requirement as the two hooks above, and the most costly
+     * one to drop: a wrapper that omits it turns a fresh deployment's first boot
+     * into a server that applies no row-level policy at all, and says nothing.
+     */
+    finalizeSecurityPosture?(driverResult: InitializedDriver): Promise<void>;
     /**
      * Read the collections schema version this database was last provisioned
      * from, or `null` when nothing has ever stamped it.
@@ -153,6 +185,13 @@ export interface DatabaseAdapter {
 export interface DatabaseAdapterInitConfig {
     /** Registered collection definitions. */
     collections: CollectionConfig[];
+    /**
+     * The data-source key this driver serves — `(default)`, or a declared
+     * one such as `analytics`. A driver given every collection needs it to
+     * know which are its own: the ones whose `dataSource` names this key, or
+     * name none when this is the default.
+     */
+    dataSourceKey?: string;
     /** The shared collection registry to register into. */
     collectionRegistry: CollectionRegistryInterface;
     /**

package/dist/types/entity_callbacks.d.ts

@@ -91,11 +91,24 @@ export type BeforeSaveProps<M extends Record<string, unknown> = Record<string, u
     id?: string | number;
 };
 /**
- * Parameters passed to hooks before a entity is saved
+ * Parameters passed to hooks when a save fails.
+ *
+ * `id` is optional because a failed create may never have been assigned one.
+ * `error` is what the save threw — the reason the hook exists. Documented since
+ * the callbacks guide first shipped, and until now not on the type or on the
+ * object: a handler that read `props.error` compiled and logged `undefined`.
+ *
  * @group Models
  */
 export type AfterSaveErrorProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = Omit<AfterSaveProps<M, USER>, "id"> & {
     id?: string | number;
+    /**
+     * Whatever the save threw: a `RebaseApiError` when a `before*` callback
+     * or a validator refused it, otherwise the driver's error with the
+     * SQLSTATE in its cause chain. Not narrowed, because a callback may
+     * throw anything.
+     */
+    error: unknown;
 };
 /**
  * Parameters passed to hooks when a entity is saved

package/dist/types/filter-operators.d.ts

@@ -225,6 +225,13 @@ export type FilterValues<Key extends string> = Partial<Record<Key, [WhereFilterO
  * closed. A typo'd relation path is refused at runtime with the target
  * collection's real column list in the message.
  *
+ * A JSON path — `metadata->>tier` — is admitted on the same terms and for the
+ * same reason. It addresses a key *inside* a `json`/`jsonb` column, so nothing
+ * in a generated row type describes it either; the driver resolves it and
+ * refuses what it cannot. It has no dot, so the dotted branch above never
+ * covered it, and every documented `?metadata->>tier=eq.gold` filter was a
+ * compile error on a typed client while working perfectly over HTTP.
+ *
  * Undotted keys are unaffected and still checked against `keyof M`.
  *
  * When `M` is left at its default `Record<string, unknown>`, `keyof M` is
@@ -234,7 +241,23 @@ export type FilterValues<Key extends string> = Partial<Record<Key, [WhereFilterO
  *
  * @group Models
  */
-export type FieldPath<M extends Record<string, unknown> = Record<string, unknown>> = Extract<keyof M, string> | `${string}.${string}`;
+export type FieldPath<M extends Record<string, unknown> = Record<string, unknown>> = Extract<keyof M, string> | NonColumnFieldPath;
+/**
+ * A field key that is not a column: a relation path (`author.name`) or a JSON
+ * path (`metadata->>tier`).
+ *
+ * The fluent builder needs this on its own, where `FindParams` does not. Its
+ * `where(column, operator, value)` types the value against `M[column]`, which
+ * only means something for a real column — so paths take a second overload
+ * whose value is `unknown`. Keying that overload on the *shape* of a path,
+ * rather than on "everything that is not a column", is what keeps a real column
+ * with a wrong value type from falling through to it and being accepted: a
+ * mistyped column name has neither a dot nor a `->>`, so it matches neither
+ * overload and is still refused.
+ *
+ * @group Models
+ */
+export type NonColumnFieldPath = `${string}.${string}` | `${string}->>${string}`;
 /**
  * Relaxed filter type that also accepts pre-serialized PostgREST strings.
  * **Internal only** — used at the wire-format boundary

package/dist/types/policy.d.ts

@@ -17,7 +17,7 @@
  *
  * @group Models
  */
-export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | AndPolicyExpression | OrPolicyExpression | NotPolicyExpression | ComparePolicyExpression | RolesOverlapPolicyExpression | RolesContainPolicyExpression | AuthenticatedPolicyExpression | ServerContextPolicyExpression | ExistsInPolicyExpression | RawPolicyExpression;
+export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | AndPolicyExpression | OrPolicyExpression | NotPolicyExpression | ComparePolicyExpression | RolesOverlapPolicyExpression | RolesContainPolicyExpression | AuthenticatedPolicyExpression | RegisteredPolicyExpression | ServerContextPolicyExpression | ExistsInPolicyExpression | RawPolicyExpression;
 /**
  * The id a request without a logged-in user reports as `rebase.uid()`.
  *
@@ -137,6 +137,33 @@ export interface RolesContainPolicyExpression {
 export interface AuthenticatedPolicyExpression {
     kind: "authenticated";
 }
+/**
+ * True for a signed-in caller who has an ACCOUNT — not a guest.
+ *
+ * The distinction {@link AuthenticatedPolicyExpression} cannot make. Anonymous
+ * SIGN-IN (`POST /auth/anonymous`) mints a real user row with a real uid and a
+ * real session, so such a caller is "authenticated" by every test that looks at
+ * `rebase.uid()`: same shape, same default role, indistinguishable inside a
+ * policy. On a deployment with anonymous sign-in enabled, every rule meaning
+ * "a signed-in person" therefore also meant "anybody at all", since pressing
+ * Continue as guest needs no email, no password and no agreement to anything.
+ *
+ * Note the two senses of "anonymous", which is the reason this was easy to
+ * miss. {@link ANONYMOUS_USER_ID} is the sentinel for a request carrying NO
+ * session, and `authenticated()` already excludes it. A guest is the other
+ * thing: a session with nobody behind it. This node excludes both.
+ *
+ * Compiles to `authenticated() AND NOT rebase.is_anonymous()`.
+ *
+ * Use it wherever a rule is about a person who could be held responsible for
+ * something — writing a review, joining an organization, spending money. Use
+ * `authenticated()` where a guest is genuinely welcome, which is what
+ * anonymous sign-in is for: a cart before checkout, a draft before signup.
+ * @group Models
+ */
+export interface RegisteredPolicyExpression {
+    kind: "registered";
+}
 /**
  * True only in the trusted **server context** — the built-in flows that run
  * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so
@@ -255,6 +282,7 @@ export declare const policy: {
     rolesOverlap: (roles: readonly string[]) => RolesOverlapPolicyExpression;
     rolesContain: (roles: readonly string[]) => RolesContainPolicyExpression;
     authenticated: () => AuthenticatedPolicyExpression;
+    registered: () => RegisteredPolicyExpression;
     serverContext: () => ServerContextPolicyExpression;
     existsIn: (args: {
         collection: string;