@rebasepro/types 0.17.3 → 0.18.1

package/src/types/history.ts

@@ -1,66 +0,0 @@
-/**
- * Entity change history — the shape a history entry has on the wire.
- *
- * This was declared three times: once in `@rebasepro/server-postgres`, once in
- * `@rebasepro/server-mongo`, and once again in the admin's `useHistory` hook.
- * The two driver copies disagreed on the one field that matters for a consumer,
- * `updated_at`, which was a `string` in Postgres and a `Date` in MongoDB — so
- * nothing could read history without first choosing a driver.
- *
- * The contract is the wire shape, and on the wire it is an ISO-8601 string.
- * A driver whose stored document differs (MongoDB keeps a `Date` and an
- * `ObjectId`) declares that storage row for itself and maps to this on the way
- * out; it is not the shared type.
- *
- * @group Backend
- */
-
-/**
- * One recorded change to a row.
- * @group Backend
- */
-export interface EntityHistoryEntry {
-    id: string;
-    /** The table (Postgres) or collection (MongoDB) the row belongs to. */
-    table_name: string;
-    /** The row's id, as a string regardless of its native type. */
-    entity_id: string;
-    action: "create" | "update" | "delete";
-    /** Which fields changed. `null` for creates and deletes. */
-    changed_fields: string[] | null;
-    values: Record<string, unknown> | null;
-    previous_values: Record<string, unknown> | null;
-    updated_by: string | null;
-    /** ISO-8601. A driver storing a native date converts on read. */
-    updated_at: string;
-}
-
-/**
- * Arguments to record one change.
- * @group Backend
- */
-export interface RecordHistoryParams {
-    tableName: string;
-    id: string;
-    action: "create" | "update" | "delete";
-    values?: Record<string, unknown> | null;
-    previousValues?: Record<string, unknown> | null;
-    updatedBy?: string | null;
-}
-
-/**
- * How much history to keep. Pruning runs per row after each write.
- * @group Backend
- */
-export interface HistoryRetentionConfig {
-    /** Max entries per row. Oldest pruned first. Default 200. */
-    maxEntries: number;
-    /** Entries older than this many days are pruned. Default 90. */
-    ttlDays: number;
-}
-
-/** @group Backend */
-export interface FetchHistoryOptions {
-    limit?: number;
-    offset?: number;
-}

package/src/types/index.ts

@@ -1,36 +0,0 @@
-export * from "./entities";
-export * from "./filter-operators";
-export * from "./chips";
-
-export * from "./properties";
-export * from "./admin_block";
-export * from "./collections";
-export * from "./search";
-export * from "./indexes";
-export * from "./relations";
-export * from "./policy";
-export * from "./rls-functions";
-export * from "./security_rules";
-
-export * from "./entity_callbacks";
-export * from "./websockets";
-export * from "./backend";
-export * from "./schema_editing";
-export * from "./channel_bus";
-export * from "./data_source";
-export * from "./resources";
-export * from "./resource_kinds";
-export * from "./storage_source";
-export * from "./cron";
-export * from "./backup";
-export * from "./component_ref";
-export * from "./auth_adapter";
-export * from "./database_adapter";
-export * from "./api_keys";
-export * from "./history";
-export * from "./postgres_introspection";
-export * from "./project_manifest";
-export * from "./collection_contract";
-export * from "./schema_version";
-export * from "./storage_authorize";
-

package/src/types/indexes.ts

@@ -1,180 +0,0 @@
-/**
- * Ordinary indexes, declared on a collection.
- *
- * Distinct from the two index-shaped things Rebase already builds. A `search`
- * block builds a GIN index over a generated `tsvector`, and a `vector`
- * property builds an ANN index over an embedding; both are structures the
- * *feature* owns and neither is a query the developer wrote. This is the plain
- * case — the btree behind a `where` clause — which had no declaration site at
- * all, so the only way to have one was to write it by hand, where the next
- * `rebase db push` planned it away.
- *
- * Every form here is core Postgres, deliberately. See {@link CollectionIndex}.
- */
-
-/**
- * A key column of an index whose access method has no ordering.
- *
- * `gin` and `brin` reject `ASC`/`DESC`/`NULLS` outright — Postgres answers
- * `access method "gin" does not support ASC/DESC options` — so those methods
- * take this narrower shape and the combination is unrepresentable rather than
- * refused at build time.
- */
-export interface UnorderedIndexKey<Keys extends string = string> {
-    /**
-     * A property key on this collection — never a column name.
-     *
-     * Which column that resolves to depends on the property, and the two
-     * differ in exactly the case an index is most often wanted for: a
-     * `belongsTo` relation compiles to its resolved `localKey`
-     * (`primaryCategory` → `primary_category_id`), not to the snake-cased
-     * property key. Anything else resolves through `columnName`, or the
-     * snake-case default when it declares none.
-     *
-     * Writing the column name here would work for most properties and quietly
-     * index nothing for a foreign key, which is the one people reach for.
-     */
-    prop: Keys | (string & {});
-}
-
-/**
- * A key column of an index, when its order matters.
- *
- * `direction` and `nulls` earn their place only when a query's `ORDER BY`
- * mixes directions. A lone `DESC` index is redundant with its `ASC` twin —
- * Postgres scans a btree backwards just as fast — and declaring both is
- * refused.
- *
- * Writing the Postgres default down explicitly is free: the derived name
- * hashes the *effective* order, so adding `direction: "asc"` to a column that
- * was already ascending is not a redefinition and rebuilds nothing.
- */
-export interface IndexKey<Keys extends string = string> extends UnorderedIndexKey<Keys> {
-    direction?: "asc" | "desc";
-    /** Postgres's own default: `last` under `asc`, `first` under `desc`. */
-    nulls?: "first" | "last";
-}
-
-/**
- * The rows a partial index covers.
- *
- * Structure rather than a SQL string, and this is the most load-bearing choice
- * in the type. A string would be replayed verbatim by Atlas in a scratch
- * database, would be the one place a caller reaches for an extension operator
- * class or a subquery, could not be checked against the collection's
- * properties, and could not be fingerprinted — its own text would have to go
- * into the derived name, so reformatting it would rename a live index.
- *
- * Structure keeps every reference resolvable at build time, keeps literals
- * going through the same quoting as the rest of the DDL, and keeps the name
- * stable under any rendering change.
- *
- * There is no `or`. An OR predicate almost always means the index should not
- * be partial at all; a caller who genuinely needs one declares two indexes.
- */
-export type IndexPredicate<Keys extends string = string> =
-    | { prop: Keys | (string & {}); op: "="; value: string | number | boolean }
-    | { prop: Keys | (string & {}); op: "!=" | "<" | "<=" | ">" | ">="; value: string | number }
-    | { prop: Keys | (string & {}); op: "is null" | "is not null" }
-    /**
-     * A non-empty list, enforced in the type. An empty `IN` is a predicate
-     * matching nothing: it builds an index over zero rows and reports success,
-     * which is the silent-empty-condition shape this codebase has been bitten
-     * by before.
-     */
-    | { prop: Keys | (string & {}); op: "in"; value: readonly [string | number, ...(string | number)[]] }
-    | { and: readonly [IndexPredicate<Keys>, ...IndexPredicate<Keys>[]] };
-
-interface BaseCollectionIndex<Keys extends string = string> {
-    /**
-     * The key columns, in order. This *is* the index's identity.
-     *
-     * Postgres can only use a leading subset, so `["ownerId", "createdAt"]`
-     * serves a query filtering on `ownerId`, and one filtering on both, and
-     * never one filtering on `createdAt` alone.
-     *
-     * Capped at five keys. Postgres allows thirty-two; past four the trailing
-     * columns are dead weight on every write, and the declaration is usually
-     * someone hoping a query gets faster by accretion. Payload columns that
-     * are not searched belong in `include`, which does not count against this.
-     */
-    on: readonly [Keys | IndexKey<Keys>, ...(Keys | IndexKey<Keys>)[]];
-
-    where?: IndexPredicate<Keys>;
-
-    /**
-     * Why this index exists, in one line. Required, and the only required
-     * field carrying no SQL.
-     *
-     * An index is the only thing a Rebase config can declare that costs money
-     * forever and whose benefit is invisible from the config. `rebase doctor`
-     * prints this beside "0 scans in 34 days, 412 MB", which is the one moment
-     * anyone is in a position to decide whether to delete it. Without it
-     * nobody can decide, so nobody does, and the table accretes indexes for
-     * the life of the product.
-     */
-    reason: string;
-}
-
-/**
- * The default. Answers equality, range, `ORDER BY`, and uniqueness.
- */
-export interface BtreeIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
-    using?: "btree";
-
-    /**
-     * A composite uniqueness guarantee.
-     *
-     * Single-column uniqueness is `validation.unique` on the property, and
-     * declaring it here is refused rather than accepted as a synonym.
-     * `validation.unique` compiles to an inline `UNIQUE` whose backing index
-     * Postgres — not Rebase — names `<table>_<column>_key`. That name is in
-     * every deployed database, appears in no contract file, and no release can
-     * reach in and rename it.
-     */
-    unique?: boolean;
-
-    /**
-     * Payload columns carried in the leaf pages, for index-only scans. Not
-     * searchable and not ordered — they save a heap fetch at the cost of a
-     * fatter index. May not overlap `on`.
-     */
-    include?: readonly (Keys | (string & {}))[];
-}
-
-/**
- * Containment over an `array` property or a JSONB `map`, using core operator
- * classes only. Trigram and full-text search are `search:`, not this.
- */
-export interface GinIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
-    using: "gin";
-    on: readonly [Keys | UnorderedIndexKey<Keys>, ...(Keys | UnorderedIndexKey<Keys>)[]];
-}
-
-/**
- * A naturally-ordered column on an append-only table — tiny, and useless the
- * moment rows arrive out of order.
- */
-export interface BrinIndex<Keys extends string = string> extends BaseCollectionIndex<Keys> {
-    using: "brin";
-    on: readonly [Keys | UnorderedIndexKey<Keys>, ...(Keys | UnorderedIndexKey<Keys>)[]];
-}
-
-/**
- * An index on a collection's table.
- *
- * No `gist` and no `hash`: every interesting gist operator class ships in an
- * extension, and hash indexes cannot be unique, composite, or ordered.
- *
- * The restriction to core Postgres is not conservatism, it is what keeps the
- * whole model on the Atlas path. `rebase db push` materialises the desired
- * state in a bare scratch database to plan against, `--exclude` does not
- * suppress that replay, and `CREATE EXTENSION` cannot be put in the file — so
- * an index needing `gin_trgm_ops` or `vector_cosine_ops` is refused at build
- * time rather than emitted to fail later against a database the author has
- * never heard of. Trigram search is `search:`; ANN is a `vector` property.
- */
-export type CollectionIndex<Keys extends string = string> =
-    | BtreeIndex<Keys>
-    | GinIndex<Keys>
-    | BrinIndex<Keys>;

package/src/types/policy.ts

@@ -1,328 +0,0 @@
-/**
- * Structured, engine-agnostic policy expressions.
- *
- * A {@link PolicyExpression} is the single source of truth for a row-level
- * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL
- * (authoritative enforcement) and independently evaluated in JavaScript (to
- * drive the admin UI, and — in future — to enforce on engines without native
- * RLS such as MongoDB). Because both the SQL and the JS decision derive from
- * the *same* expression, the UI matches database enforcement by construction —
- * no drift between two hand-written implementations.
- *
- * The only escape hatch that cannot be evaluated client-side is the
- * {@link RawPolicyExpression} node (`{ kind: "raw" }`): it preserves full
- * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the
- * JavaScript evaluator (never silently allowed) and reflected exactly in the UI
- * via server-computed capability flags.
- *
- * @group Models
- */
-export type PolicyExpression =
-    | TruePolicyExpression
-    | FalsePolicyExpression
-    | AndPolicyExpression
-    | OrPolicyExpression
-    | NotPolicyExpression
-    | ComparePolicyExpression
-    | RolesOverlapPolicyExpression
-    | RolesContainPolicyExpression
-    | AuthenticatedPolicyExpression
-    | ServerContextPolicyExpression
-    | ExistsInPolicyExpression
-    | RawPolicyExpression;
-
-/**
- * The id a request without a logged-in user reports as `rebase.uid()`.
- *
- * A user-context request always sets `app.uid`: blank would read back as
- * `NULL`, and `NULL` is how the trusted server context is recognised, so an
- * anonymous visitor would be promoted to server privileges. The driver
- * therefore substitutes this sentinel at the single chokepoint where the GUC
- * is set.
- *
- * The consequence for policy authors is that **`rebase.uid() IS NOT NULL` is a
- * tautology on the user path** — it is true for anonymous visitors too. Use
- * {@link policy.authenticated} to mean "signed in", and
- * {@link policy.serverContext} to mean "the trusted server context". Do not
- * hand-write the comparison: see {@link ANONYMOUS_USER_IDS} for why one
- * literal is not enough.
- *
- * @group Models
- */
-export const ANONYMOUS_USER_ID = "anonymous";
-
-/**
- * Every uid that has ever meant "nobody is signed in" — newest first.
- *
- * There are two because there were two. The types, the policy compiler, the
- * JavaScript evaluator and the linter were all built on
- * {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated
- * callers as `'anon'` — so `policy.authenticated()`, which compiled to
- * `rebase.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
- * sanctioned way to write "signed in" granted to everyone, and the linter
- * flagged the spelling that actually worked as a foreign convention.
- *
- * The request path now reports {@link ANONYMOUS_USER_ID}. `'anon'` stays here
- * because policies outlive the server that generated them: a database still
- * holding policies from before the fix, or a project whose server has not been
- * upgraded yet, must not become a grant in either direction. Compile against
- * this list, not against a single literal.
- *
- * No real user id is ever one of these, so a match is always "not signed in".
- *
- * @group Models
- */
-export const ANONYMOUS_USER_IDS: readonly string[] = [ANONYMOUS_USER_ID, "anon"];
-
-/**
- * Whether a uid stands for "no one is signed in", in any spelling rebase has
- * used. `null`/`undefined` is the trusted server context, not an anonymous
- * caller, and is therefore **not** anonymous — see {@link ANONYMOUS_USER_ID}.
- *
- * @group Models
- */
-export function isAnonymousUid(uid: string | null | undefined): boolean {
-    return typeof uid === "string" && ANONYMOUS_USER_IDS.includes(uid);
-}
-
-/** Always allows. Compiles to `true`. @group Models */
-export interface TruePolicyExpression {
-    kind: "true";
-}
-
-/** Always denies. Compiles to `false`. @group Models */
-export interface FalsePolicyExpression {
-    kind: "false";
-}
-
-/** Logical AND — every operand must pass. @group Models */
-export interface AndPolicyExpression {
-    kind: "and";
-    operands: readonly PolicyExpression[];
-}
-
-/** Logical OR — at least one operand must pass. @group Models */
-export interface OrPolicyExpression {
-    kind: "or";
-    operands: readonly PolicyExpression[];
-}
-
-/** Logical negation. @group Models */
-export interface NotPolicyExpression {
-    kind: "not";
-    operand: PolicyExpression;
-}
-
-/** Comparison operators available to {@link ComparePolicyExpression}. @group Models */
-export type PolicyCompareOperator = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
-
-/**
- * Compares two operands, e.g. `owner_id = rebase.uid()`.
- * @group Models
- */
-export interface ComparePolicyExpression {
-    kind: "compare";
-    op: PolicyCompareOperator;
-    left: PolicyOperand;
-    right: PolicyOperand;
-}
-
-/**
- * True when the user holds *at least one* of the given application roles.
- * Compiles to `string_to_array(rebase.roles(), ',') && ARRAY[...]`.
- * @group Models
- */
-export interface RolesOverlapPolicyExpression {
-    kind: "rolesOverlap";
-    roles: readonly string[];
-}
-
-/**
- * True when the user holds *all* of the given application roles.
- * Compiles to `string_to_array(rebase.roles(), ',') @> ARRAY[...]`.
- * @group Models
- */
-export interface RolesContainPolicyExpression {
-    kind: "rolesContain";
-    roles: readonly string[];
-}
-
-/**
- * True when a signed-in user is making the request. Compiles to
- * `rebase.uid() IS NOT NULL AND rebase.uid() <> 'anonymous'`.
- *
- * Both halves are load-bearing. `IS NOT NULL` excludes the server context;
- * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who
- * *do* carry a non-null `rebase.uid()`. Checking only `IS NOT NULL` grants to
- * everyone — see {@link ANONYMOUS_USER_ID}.
- *
- * `policy.not(policy.authenticated())` therefore means "anonymous visitor or
- * the server context". To single out the server context, use
- * {@link ServerContextPolicyExpression}.
- * @group Models
- */
-export interface AuthenticatedPolicyExpression {
-    kind: "authenticated";
-}
-
-/**
- * True only in the trusted **server context** — the built-in flows that run
- * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so
- * `rebase.uid()` is `NULL` for them and only for them. Compiles to
- * `rebase.uid() IS NULL`.
- *
- * This is what lets the owner connection satisfy a policy even under FORCE RLS.
- * It is deliberately a primitive rather than `not(authenticated())`: the two
- * meant the same thing while `authenticated` ignored {@link ANONYMOUS_USER_ID},
- * and conflating them is what turns a server-only grant into an anonymous one.
- *
- * The JavaScript evaluator always returns `false` for this node — a client is
- * never the server context.
- * @group Models
- */
-export interface ServerContextPolicyExpression {
-    kind: "serverContext";
-}
-
-/**
- * Membership / relational access: true when at least one row exists in another
- * collection (a join/membership table) matching `where`. This is what lets you
- * scope reads to "rows whose team the caller belongs to" without an N+1
- * per-row lookup — it compiles to a single correlated `EXISTS` subquery.
- *
- * Inside `where`, {@link FieldPolicyOperand} (`policy.field`) references a column
- * of the joined collection, while {@link OuterFieldPolicyOperand}
- * (`policy.outerField`) references a column of the row being checked (the outer
- * table under RLS). Combine with {@link AuthUidPolicyOperand} to correlate to
- * the caller.
- *
- * @example
- * ```ts
- * // documents visible only to members of the document's team:
- * policy.existsIn({
- *   collection: "team_members",
- *   where: policy.and(
- *     policy.compare(policy.field("team_id"), "eq", policy.outerField("team_id")),
- *     policy.compare(policy.field("user_id"), "eq", policy.authUid()),
- *   ),
- * })
- * // → EXISTS (SELECT 1 FROM team_members _ex0
- * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = rebase.uid())
- * ```
- *
- * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript
- * evaluator treats it as *unknown* (it cannot run a subquery client-side), so
- * enforcement is always the database's.
- * @group Models
- */
-export interface ExistsInPolicyExpression {
-    kind: "existsIn";
-    /** Slug of the collection to search (the join / membership table). */
-    collection: string;
-    /** Condition evaluated against the joined collection's rows. */
-    where: PolicyExpression;
-}
-
-/**
- * A raw PostgreSQL boolean expression — the full-power escape hatch.
- *
- * Columns can be referenced as `{column_name}`. This is Postgres-only and
- * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary
- * SQL, so it treats this node as *unknown* rather than guessing.
- * @group Models
- */
-export interface RawPolicyExpression {
-    kind: "raw";
-    sql: string;
-}
-
-/**
- * An operand referenced by a {@link ComparePolicyExpression}.
- * @group Models
- */
-export type PolicyOperand =
-    | FieldPolicyOperand
-    | OuterFieldPolicyOperand
-    | LiteralPolicyOperand
-    | AuthUidPolicyOperand
-    | AuthRolesPolicyOperand;
-
-/** A column value on the row being evaluated. @group Models */
-export interface FieldPolicyOperand {
-    kind: "field";
-    /** The property/column name (resolved to its DB column when compiled). */
-    name: string;
-}
-
-/**
- * A column value on the *outer* row when used inside {@link ExistsInPolicyExpression}
- * — i.e. the row the RLS policy is being evaluated for, referenced from within the
- * subquery. Outside an `existsIn` it is equivalent to {@link FieldPolicyOperand}.
- * @group Models
- */
-export interface OuterFieldPolicyOperand {
-    kind: "outerField";
-    /** The property/column name on the outer collection. */
-    name: string;
-}
-
-/** A constant value. @group Models */
-export interface LiteralPolicyOperand {
-    kind: "literal";
-    value: string | number | boolean | null;
-}
-
-/** The current user's id — compiles to `rebase.uid()`. @group Models */
-export interface AuthUidPolicyOperand {
-    kind: "authUid";
-}
-
-/**
- * The current user's roles as an array — compiles to
- * `string_to_array(rebase.roles(), ',')`.
- * @group Models
- */
-export interface AuthRolesPolicyOperand {
-    kind: "authRoles";
-}
-
-// ── Constructor helpers ──────────────────────────────────────────────
-// Small, dependency-free builders so callers (and the desugaring in
-// `@rebasepro/common`) can assemble expressions without object-literal noise.
-
-/** @group Models */
-export const policy = {
-    true: (): TruePolicyExpression => ({ kind: "true" }),
-    false: (): FalsePolicyExpression => ({ kind: "false" }),
-    and: (...operands: readonly PolicyExpression[]): AndPolicyExpression => ({ kind: "and",
-operands: operands as PolicyExpression[] }),
-    or: (...operands: readonly PolicyExpression[]): OrPolicyExpression => ({ kind: "or",
-operands: operands as PolicyExpression[] }),
-    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: "not",
-operand }),
-    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>
-        ({ kind: "compare",
-op,
-left,
-right }),
-    rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: "rolesOverlap",
-roles: roles as string[] }),
-    rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: "rolesContain",
-roles: roles as string[] }),
-    authenticated: (): AuthenticatedPolicyExpression => ({ kind: "authenticated" }),
-    serverContext: (): ServerContextPolicyExpression => ({ kind: "serverContext" }),
-    existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>
-        ({ kind: "existsIn",
-collection: args.collection,
-where: args.where }),
-    raw: (sql: string): RawPolicyExpression => ({ kind: "raw",
-sql }),
-    field: (name: string): FieldPolicyOperand => ({ kind: "field",
-name }),
-    outerField: (name: string): OuterFieldPolicyOperand => ({ kind: "outerField",
-name }),
-    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: "literal",
-value }),
-    authUid: (): AuthUidPolicyOperand => ({ kind: "authUid" }),
-    authRoles: (): AuthRolesPolicyOperand => ({ kind: "authRoles" })
-};