@rebasepro/types 0.17.3 → 0.18.1

package/src/types/resources.ts

@@ -1,368 +0,0 @@
-/**
- * The resource graph: one declaration site for every named thing a project needs.
- *
- * ## The rule
- *
- * **Every named resource is declared with a constructor in config code.** A
- * database, a bucket, a topic and whatever kind comes next are all spelled the
- * same way, so "where do I declare my second one" has one answer instead of one
- * answer per kind.
- *
- * ```ts
- * export const main    = database("main");
- * export const media   = bucket("media", { transport: "direct" });
- * export const signups = topic<SignupEvent>("signups");
- * ```
- *
- * ## Declaration is not binding
- *
- * A declaration says a resource *exists* and what shape it has. It never says
- * how to reach it — that is a property of the environment, not of the project,
- * and it differs between a laptop, a self-hosted box and a tenant in the cloud.
- * Binding lives in `@rebasepro/server`'s boot path, reading environment
- * variables or an infrastructure config file, and it keys off the logical name
- * declared here.
- *
- * This split is the whole point. Before it, storage topology was hand-written
- * into `rebase.json` while database topology lived in TypeScript, and the
- * boundary between them was a fact about what the control plane could read
- * before a build — a platform implementation detail that a developer had no way
- * to derive. Worse, storage could be declared in *both* places, and the merge
- * silently kept the JSON's engine and discarded the code's.
- *
- * ## Why a registry rather than a fixed union
- *
- * Kinds register themselves. Adding pub/sub, a cache or a search index must not
- * require editing a manifest schema, a validator and three switch statements —
- * that cost is exactly why the last two kinds ended up in different homes.
- */
-
-/** How a client reaches a resource. */
-export type ResourceTransport =
-    /** Through the backend. The default, and the only one that needs no client SDK. */
-    | "server"
-    /** A provider SDK talks to the resource directly; the backend is not in the path. */
-    | "direct";
-
-/**
- * A resource kind, as registered.
- *
- * `engines` is an allowlist rather than documentation. An unrecognised engine
- * used to be a free string that passed every check and failed later, further
- * from the typo that caused it — `"s2"` for `"s3"` reached the runtime. Anything
- * genuinely outside the list is spelled `custom:<id>`, which says so at the call
- * site instead of looking like a typo.
- */
-export interface ResourceKindSpec {
-    /** The kind's name, as it appears in a declaration and in the graph. */
-    kind: string;
-    /** Engines this kind ships with. `custom:<id>` is always additionally valid. */
-    engines: readonly string[];
-    /** Used when a declaration names none. */
-    defaultEngine: string;
-    /**
-     * Environment variable base names this kind binds from, in the order a
-     * binder should try them. A resource keyed `analytics` reads
-     * `<BASE>__ANALYTICS`; the default-keyed resource reads `<BASE>` unsuffixed,
-     * so a single-resource project configured the obvious way declares nothing.
-     */
-    envBases: readonly string[];
-    /**
-     * The subset of `envBases` that matters for a given engine.
-     *
-     * The binder reads every base and takes whichever is set — harmless, and it
-     * keeps binding tolerant. A GENERATOR cannot be that relaxed: `rebase eject
-     * infra` writing S3_BUCKET, GCS_BUCKET, STORAGE_BUCKET and
-     * STORAGE_PUBLIC_URL for a `local` bucket hands somebody four variables of
-     * which three are noise, and a config file full of irrelevant keys is one
-     * nobody reads carefully.
-     *
-     * Keyed by engine; an engine with no entry falls back to all of them, which
-     * is the honest answer for one this package has never heard of.
-     */
-    envBasesByEngine?: Readonly<Record<string, readonly string[]>>;
-    /** Option keys this kind accepts beyond the common ones, for validation. */
-    optionKeys?: readonly string[];
-    /**
-     * Whether a project implicitly has one of these even when it declares
-     * nothing. True for databases — a backend without one is not a backend —
-     * and false for topics, where zero is the normal number.
-     */
-    implicitDefault?: boolean;
-}
-
-/** The key a resource takes when a project declares only one of its kind. */
-export const DEFAULT_RESOURCE_KEY = "(default)";
-
-/** A declared resource, as it appears in the graph. */
-export interface ResourceDeclaration {
-    kind: string;
-    /** Unique within its kind. What a binder looks up and what an env suffix is built from. */
-    key: string;
-    engine: string;
-    transport: ResourceTransport;
-    label?: string;
-    /** Kind-specific options, validated against the kind's `optionKeys`. */
-    options: Readonly<Record<string, unknown>>;
-}
-
-/**
- * The value a constructor returns.
- *
- * Carries its own declaration so config code can hold it and pass it around,
- * and stringifies to its key so it drops into the places that still take one.
- * Collections name a data source by string today; a handle works there without
- * the collection API having to change, which keeps this a config redesign
- * rather than a rewrite of the data layer.
- */
-export interface ResourceHandle extends ResourceDeclaration {
-    toString(): string;
-}
-
-const BRAND = Symbol.for("@rebasepro/types.resource");
-
-/** Whether a value is a resource handle rather than a plain string key. */
-export function isResourceHandle(value: unknown): value is ResourceHandle {
-    return typeof value === "object" && value !== null && BRAND in value;
-}
-
-/** The key a resource reference names, whether it is a handle or already a key. */
-export function resourceKeyOf(ref: string | ResourceHandle): string {
-    return isResourceHandle(ref) ? ref.key : ref;
-}
-
-/**
- * The process-wide registry.
- *
- * Keyed off `globalThis` through a shared symbol rather than held in a module
- * local, because a module local is per *copy* of this package. A project that
- * ends up with two copies of `@rebasepro/types` — which a partially-linked
- * `node_modules` produces, and which has already caused a phantom
- * "JWT secret not configured" bug in this repo — would otherwise register into
- * one registry and read from the other, and see an empty graph with nothing
- * anywhere to explain it.
- */
-interface Registry {
-    kinds: Map<string, ResourceKindSpec>;
-    declarations: Map<string, ResourceDeclaration>;
-}
-
-const GLOBAL_KEY = Symbol.for("@rebasepro/types.resourceRegistry");
-
-function registry(): Registry {
-    const g = globalThis as unknown as Record<symbol, Registry | undefined>;
-    let existing = g[GLOBAL_KEY];
-    if (!existing) {
-        existing = { kinds: new Map(), declarations: new Map() };
-        g[GLOBAL_KEY] = existing;
-    }
-    return existing;
-}
-
-/** `kind:key`, the graph's primary key. */
-function declarationId(kind: string, key: string): string {
-    return `${kind}:${key}`;
-}
-
-/** Register a resource kind. Idempotent for an identical spec; throws on a conflicting one. */
-export function registerResourceKind(spec: ResourceKindSpec): void {
-    const existing = registry().kinds.get(spec.kind);
-    if (existing && JSON.stringify(existing) !== JSON.stringify(spec)) {
-        throw new Error(
-            `Resource kind "${spec.kind}" is already registered with a different definition. ` +
-            "Two packages cannot define the same kind."
-        );
-    }
-    registry().kinds.set(spec.kind, spec);
-}
-
-/** Every registered kind, for validators and for `rebase doctor`. */
-export function resourceKinds(): ResourceKindSpec[] {
-    return [...registry().kinds.values()];
-}
-
-/** One registered kind, or undefined. */
-export function resourceKind(kind: string): ResourceKindSpec | undefined {
-    return registry().kinds.get(kind);
-}
-
-/** Options every kind accepts. */
-export interface DeclareOptions {
-    engine?: string;
-    transport?: ResourceTransport;
-    label?: string;
-    [option: string]: unknown;
-}
-
-const COMMON_OPTION_KEYS = ["engine", "transport", "label"] as const;
-
-/** Whether an engine is one the kind knows, or an explicit `custom:` opt-out. */
-export function isValidEngine(spec: ResourceKindSpec, engine: string): boolean {
-    return engine.startsWith("custom:") || spec.engines.includes(engine);
-}
-
-/**
- * Declare a resource. The primitive every kind's constructor is built from.
- *
- * Redeclaring the same `kind:key` with a *different* shape throws rather than
- * merging. Merging is what the old storage path did, and it silently discarded
- * one of the two engines — a declaration accepted and then ignored, which is
- * the failure this whole model exists to remove. Redeclaring it identically is
- * fine: a config module evaluated twice must not be an error.
- */
-export function declareResource(
-    kind: string,
-    key: string = DEFAULT_RESOURCE_KEY,
-    options: DeclareOptions = {}
-): ResourceHandle {
-    const spec = registry().kinds.get(kind);
-    if (!spec) {
-        const known = [...registry().kinds.keys()].sort().join(", ") || "none";
-        throw new Error(
-            `Unknown resource kind "${kind}". Registered kinds: ${known}. ` +
-            "Call registerResourceKind() before declaring one."
-        );
-    }
-
-    if (!key || typeof key !== "string" || key.trim() === "") {
-        throw new Error(`A ${kind} needs a non-empty key.`);
-    }
-
-    const engine = options.engine ?? spec.defaultEngine;
-    if (!isValidEngine(spec, engine)) {
-        throw new Error(
-            `Unknown ${kind} engine "${engine}" for "${key}". ` +
-            `Known engines: ${spec.engines.join(", ")}. ` +
-            `An engine this build does not ship is spelled "custom:${engine}", ` +
-            "which says so at the call site rather than failing later."
-        );
-    }
-
-    const allowed = new Set<string>([...COMMON_OPTION_KEYS, ...(spec.optionKeys ?? [])]);
-    const unknown = Object.keys(options).filter(k => !allowed.has(k));
-    if (unknown.length > 0) {
-        throw new Error(
-            `Unknown option(s) on ${kind} "${key}": ${unknown.join(", ")}. ` +
-            `A ${kind} accepts: ${[...allowed].sort().join(", ")}.`
-        );
-    }
-
-    const extra: Record<string, unknown> = {};
-    for (const k of spec.optionKeys ?? []) {
-        if (options[k] !== undefined) extra[k] = options[k];
-    }
-
-    const declaration: ResourceDeclaration = {
-        kind,
-        key,
-        engine,
-        transport: options.transport ?? "server",
-        ...(options.label !== undefined ? { label: options.label } : {}),
-        options: Object.freeze(extra)
-    };
-
-    const id = declarationId(kind, key);
-    const previous = registry().declarations.get(id);
-    if (previous) {
-        if (JSON.stringify(previous) !== JSON.stringify(declaration)) {
-            throw new Error(
-                `${kind} "${key}" is declared twice with different configuration. ` +
-                "Declare it once and export it — two declarations of one resource is " +
-                "the ambiguity this model exists to remove, so it is refused rather " +
-                "than merged."
-            );
-        }
-    } else {
-        registry().declarations.set(id, declaration);
-    }
-
-    const handle = {
-        ...declaration,
-        toString() { return key; },
-        [BRAND]: true as const
-    };
-    return handle as ResourceHandle;
-}
-
-/** Every declared resource, in declaration order, optionally filtered by kind. */
-export function declaredResources(kind?: string): ResourceDeclaration[] {
-    const all = [...registry().declarations.values()];
-    return kind ? all.filter(r => r.kind === kind) : all;
-}
-
-/**
- * Forget every declaration, keeping registered kinds.
- *
- * For tests and for a CLI that evaluates more than one project in a process.
- * Kinds survive because they are registered by module import, which will not
- * happen a second time.
- */
-export function resetDeclaredResources(): void {
-    registry().declarations.clear();
-}
-
-/**
- * The env-var suffix a resource's bindings use: `__ANALYTICS` for `analytics`,
- * and nothing at all for the default-keyed one.
- *
- * The default takes no suffix so that a project with one database configured
- * through plain `DATABASE_URL` keeps working having declared nothing — the
- * overwhelmingly common project must not have to say so.
- */
-export function resourceEnvSuffix(key: string): string {
-    if (key === DEFAULT_RESOURCE_KEY) return "";
-    return `__${key.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
-}
-
-/**
- * Two resources of a kind whose keys differ but whose env suffixes do not.
- *
- * `media-files` and `media_files` both become `__MEDIA_FILES`, so one would
- * silently read the other's configuration. Returned rather than thrown so the
- * caller can report it with the rest of a validation pass.
- */
-export function findEnvSuffixCollision(keys: readonly string[]): { a: string; b: string; suffix: string } | null {
-    const seen = new Map<string, string>();
-    for (const key of keys) {
-        const suffix = resourceEnvSuffix(key);
-        const previous = seen.get(suffix);
-        if (previous !== undefined && previous !== key) return { a: previous, b: key, suffix };
-        seen.set(suffix, key);
-    }
-    return null;
-}
-
-/**
- * The whole graph, as recorded in a manifest and read by a host.
- *
- * `version` is the graph format, not the project's. A host reading a graph it
- * does not understand must say so rather than provision half of it.
- */
-export interface ResourceGraph {
-    version: 1;
-    resources: ResourceDeclaration[];
-}
-
-/** The current graph format version. */
-export const RESOURCE_GRAPH_VERSION = 1 as const;
-
-/** Build a graph from the current declarations, sorted for a stable diff. */
-export function buildResourceGraph(): ResourceGraph {
-    const resources = declaredResources().slice().sort(
-        (a, b) => a.kind.localeCompare(b.kind) || a.key.localeCompare(b.key)
-    );
-    return { version: RESOURCE_GRAPH_VERSION, resources };
-}
-
-/**
- * The environment variables worth writing for a resource, given its engine.
- *
- * Falls back to every base the kind reads when the engine is unknown — a
- * `custom:` engine gets the full list rather than an empty one, because
- * guessing narrow would silently omit the variable it actually needs.
- */
-export function envBasesForResource(declaration: ResourceDeclaration): readonly string[] {
-    const spec = resourceKind(declaration.kind);
-    if (!spec) return [];
-    return spec.envBasesByEngine?.[declaration.engine] ?? spec.envBases;
-}

package/src/types/rls-functions.ts

@@ -1,98 +0,0 @@
-/**
- * The SQL helper functions RLS policies call, and the schema they live in.
- *
- * ## One schema, and it is ours
- *
- * Rebase creates exactly one schema in a project's database: `rebase`. These
- * three functions live in it alongside the framework's own tables, and that is
- * the whole contract — a reader can look at a database and know precisely which
- * namespace belongs to the framework and that nothing else was touched.
- *
- * It used to be two. `uid()`, `jwt()` and `roles()` sat in a schema called
- * `auth`, which is Supabase's name, chosen so that a developer who had written
- * Supabase RLS would recognise `auth.uid()`. The familiarity was real but the
- * name was not Rebase's to take, and taking it had a concrete cost: pointing
- * Rebase at a database that already had a Supabase `auth` schema meant
- * `CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` against Supabase's
- * `RETURNS uuid`, which Postgres rejects outright —
- *
- *     ERROR:  cannot change return type of existing function
- *     HINT:   Use DROP FUNCTION auth.uid() first.
- *
- * — and the failure landed inside a catch-all that logged a warning and carried
- * on, leaving a database with auth tables, no helper functions, and policies
- * calling functions that did not exist. Under `rebase db migrate` the same
- * statements aborted the migration instead.
- *
- * `rebase.uid()` collides with nobody. A Supabase database keeps its `auth`
- * schema untouched and gains a `rebase` one, which is what a gradual migration
- * needs.
- *
- * ## Why functions at all, rather than inlining `current_setting`
- *
- * Because the indirection has already been spent once. `uid()` resolves
- * `app.uid` and falls back to the pre-rename `app.user_id`, so that during a
- * rolling deploy — old and new pods serving one database — both eras resolve
- * the principal. That was a single `CREATE OR REPLACE`. Inlined into policy
- * bodies it would have been a rewrite of every policy on every table.
- *
- * ## Why the name is not configurable
- *
- * A policy body is stored SQL: Postgres parses `USING (…)` once and keeps it, so
- * these strings are written into every policy in every database Rebase has
- * provisioned. Everything that reads policies back — the SQL-to-policy parser
- * behind the admin UI, the drift checker, `rls-check` — would have to know the
- * configured value to recognise its own output. One frozen name is the feature.
- */
-
-/** The schema Rebase owns. The only schema Rebase creates. */
-export const REBASE_SCHEMA = "rebase";
-
-/**
- * The principal of the current request, as text, or NULL in the server context.
- *
- * Never NULL for a user request — an anonymous one carries
- * {@link ANONYMOUS_USER_ID} — which is what makes `IS NULL` a reliable test for
- * the trusted server plane and `IS NOT NULL` a tautology.
- */
-export const RLS_UID_SQL = `${REBASE_SCHEMA}.uid()`;
-
-/** The request's roles as a comma-separated string, for `string_to_array`. */
-export const RLS_ROLES_SQL = `${REBASE_SCHEMA}.roles()`;
-
-/** The request's JWT claims as `jsonb`, or `{}`. */
-export const RLS_JWT_SQL = `${REBASE_SCHEMA}.jwt()`;
-
-/**
- * The pre-1.0 spellings, for recognising policies and hand-written SQL that
- * predate the move.
- *
- * Kept because policies outlive the server that wrote them: a database migrated
- * by an older release still holds `auth.uid()` in its policy bodies until the
- * next push or boot recompiles them, and anything that reads policies back has
- * to recognise both eras or report the framework's own output as foreign drift.
- * Also used to give a project whose `securityRules` contain raw `auth.uid()` a
- * message naming the replacement, instead of a parse failure.
- */
-export const LEGACY_RLS_SCHEMA = "auth";
-export const LEGACY_RLS_UID_SQL = `${LEGACY_RLS_SCHEMA}.uid()`;
-export const LEGACY_RLS_ROLES_SQL = `${LEGACY_RLS_SCHEMA}.roles()`;
-export const LEGACY_RLS_JWT_SQL = `${LEGACY_RLS_SCHEMA}.jwt()`;
-
-/**
- * Rewrites the pre-1.0 function calls in a fragment of policy SQL.
- *
- * Deliberately anchored on a word boundary and the schema qualifier, so a column
- * called `auth_uid` or a table named `auth` is left alone.
- */
-export function rewriteLegacyRlsFunctions(sql: string): string {
-    return sql.replace(
-        /\bauth\.(uid|jwt|roles)\s*\(\s*\)/gi,
-        (_match, fn: string) => `${REBASE_SCHEMA}.${fn.toLowerCase()}()`
-    );
-}
-
-/** Whether a fragment of SQL still calls the pre-1.0 functions. */
-export function usesLegacyRlsFunctions(sql: string): boolean {
-    return /\bauth\.(uid|jwt|roles)\s*\(\s*\)/i.test(sql);
-}

package/src/types/schema_editing.ts

@@ -1,157 +0,0 @@
-/**
- * The vocabulary a live schema change is described in.
- *
- * Declared here, and nowhere else, because two packages that must not import
- * each other both need it: `@rebasepro/server-postgres` decides what a change
- * means and renders the files it needs, while `@rebasepro/server` commits those
- * files and serves the routes. Neither can reach the other — the server is
- * engine-agnostic by design — so the shared kernel holds the shapes and the
- * driver is detected structurally through {@link SchemaEditingAdmin}.
- *
- * Nothing here executes anything. These are the nouns.
- */
-
-/**
- * What a change will do to a live database.
- *
- * - `safe` — the boot-time ensure path expresses it, and the result matches the
- *   configuration.
- * - `diverges` — the ensure path applies *something*, but the database will not
- *   match what the configuration declares, and nothing reports it. This is the
- *   category worth having: adding a required property to a populated table
- *   yields a nullable column, and adding a value to an existing enum yields
- *   nothing at all. Both read as success.
- * - `needs-migration` — the ensure path cannot express it. Dropping anything,
- *   changing a type, moving a primary key.
- */
-export type SchemaChangeVerdict = "safe" | "diverges" | "needs-migration";
-
-export type SchemaChangeKind =
-    | "add-collection"
-    | "remove-collection"
-    | "add-property"
-    | "remove-property"
-    | "change-property-type"
-    | "rename-column"
-    | "add-enum-value"
-    | "remove-enum-value"
-    | "change-required"
-    | "change-primary-key";
-
-export interface SchemaChange {
-    kind: SchemaChangeKind;
-    verdict: SchemaChangeVerdict;
-    /** Collection slug. */
-    collection: string;
-    /** Property name, where the change is to one. */
-    property?: string;
-    /** One line, specific: what changed and what it will do. */
-    detail: string;
-    /** What to do instead, when the verdict is not `safe`. */
-    remedy?: string;
-}
-
-export interface ClassifiedSchemaChanges {
-    changes: SchemaChange[];
-    /** The worst verdict present, or `safe` for an empty diff. */
-    verdict: SchemaChangeVerdict;
-    /** True only when every change is `safe` — the one case an editor may apply. */
-    applicable: boolean;
-}
-
-/**
- * Where a project's generated schema artifacts live, relative to the **project**
- * root — which is the repository root only when the project is the whole
- * repository.
- *
- * Here rather than in the Postgres package because it is a contract, not an
- * engine detail: `@rebasepro/server` has to derive these for a project in a
- * subdirectory, and it cannot import a driver to do it.
- */
-export interface SchemaCommitPaths {
-    /** Drizzle schema, imported by the backend. */
-    schemaFile: string;
-    /** Declarative DDL, what `db push` applies and Atlas diffs against. */
-    ddlFile: string;
-    policiesFile: string;
-    searchFile: string;
-    /** Vector columns and ANN indexes — like search, applied by Rebase not Atlas. */
-    vectorFile: string;
-}
-
-export const DEFAULT_COMMIT_PATHS: SchemaCommitPaths = {
-    schemaFile: "backend/src/schema.generated.ts",
-    ddlFile: "drizzle/schema.sql",
-    policiesFile: "drizzle/policies.sql",
-    searchFile: "drizzle/search.sql",
-    vectorFile: "drizzle/vector.sql"
-};
-
-/** One file the commit writes, as content rather than as a path on a disk. */
-export interface SchemaChangeFile {
-    path: string;
-    contents: string;
-}
-
-/**
- * Everything a change needs written and run.
- *
- * Computed without touching a disk or a network. The database is *read* — what
- * a change means depends on what is already there, and a plan that guessed
- * would be guessing about whether the statements it returns will be accepted.
- */
-export interface SchemaChangePlan {
-    /** Every file the commit writes — collection source and generated artifacts. */
-    files: SchemaChangeFile[];
-    /** The additive DDL this change adds, in dependency order. */
-    statements: string[];
-    classified: ClassifiedSchemaChanges;
-    /** A commit message describing the change rather than announcing one. */
-    message: string;
-    /**
-     * Constraints the configuration asks for that these statements do not
-     * carry, and why.
-     *
-     * Almost always empty. When it is not, it is the part the person confirming
-     * needs to read: the change will apply, and the database will still not
-     * enforce something the configuration says — a required property over a
-     * table that already holds rows with no value for it. Optional so a plan
-     * from an engine that does not distinguish these cases stays valid.
-     */
-    withheldConstraints?: WithheldSchemaConstraint[];
-}
-
-/** A constraint a plan asks for and does not apply. */
-export interface WithheldSchemaConstraint {
-    /** `schema.table.column`. */
-    target: string;
-    kind: "not-null";
-    /** What is in the way, naming the obstacle rather than the rule. */
-    reason: string;
-    /** What would make it applicable. */
-    remedy: string;
-}
-
-/**
- * An admin that can plan a schema change.
- *
- * Planning only. Applying is `executeSql`, which every SQL admin already has,
- * and committing belongs to whatever holds the repository — keeping those three
- * apart is what lets the same plan be committed locally on a developer's machine
- * and through a GitHub App from a cloud tenant.
- *
- * @group Admin
- */
-export interface SchemaEditingAdmin {
-    /**
-     * Decide what the change means and render everything it needs.
-     *
-     * Rejects when the change is not applicable, carrying the classification so
-     * a caller can say which change was the problem.
-     */
-    planSchemaChange(
-        before: unknown[],
-        after: unknown[],
-        options?: { paths?: Partial<SchemaCommitPaths> }
-    ): Promise<SchemaChangePlan>;
-}