@rebasepro/types 0.17.3 → 0.18.1

package/src/types/relations.ts

@@ -1,417 +0,0 @@
-import type { AnyCollectionConfig } from "./collections";
-
-/**
- * @group Models
- */
-export type OnAction = "cascade" | "restrict" | "no action" | "set null" | "set default";
-
-/**
- * What kind of link a relation is.
- *
- * The discriminant. Every other field a relation carries belongs to exactly one
- * of these, which is the point: a relation used to be a single open interface
- * where `cardinality`, `direction`, `localKey`, `foreignKeyOnTarget`, `through`
- * and `joinPath` were all optional and any combination typechecked. Which link
- * you meant then had to be *inferred* from which fields you happened to set,
- * and the inference was ~200 lines that guessed, fell back on naming
- * conventions, and swallowed its own failures.
- *
- * Most of that guessing produced bugs rather than convenience. A `many`
- * relation carrying a `localKey` — a combination the old type permitted — made
- * the write path stamp the parent's own foreign key onto the child row. Under
- * these kinds that state cannot be written down.
- *
- * @group Models
- */
-export type RelationKind = "belongsTo" | "hasOne" | "hasMany" | "manyToMany" | "via";
-
-/** Fields every relation carries, whatever its kind. @group Models */
-export interface RelationBase {
-    /**
-     * The name this link is addressed by: the key in `include`, the tab in the
-     * admin panel, and the path segment of a nested URL.
-     *
-     * Defaults to the declaring property's key, or to the target's slug for an
-     * entry in `relations`.
-     */
-    relationName?: string;
-
-    /** The collection on the other end. */
-    target: () => AnyCollectionConfig;
-
-    onUpdate?: OnAction;
-    onDelete?: OnAction;
-
-    /** Presentation overrides applied when this relation is rendered as a tab. */
-    overrides?: Partial<AnyCollectionConfig>;
-
-    validation?: {
-        required?: boolean;
-    };
-}
-
-/**
- * This collection holds the foreign key. One target row per source row.
- *
- * ```ts
- * author: { kind: "belongsTo", target: () => authors, localKey: "author_id" }
- * ```
- * @group Models
- */
-export interface BelongsToRelation extends RelationBase {
-    kind: "belongsTo";
-    /**
-     * Column on **this** collection's table holding the target's key.
-     * Defaults to `<relationName>_id`.
-     */
-    localKey?: string;
-}
-
-/**
- * The target holds the foreign key, and at most one target row points back.
- *
- * ```ts
- * profile: { kind: "hasOne", target: () => profiles, foreignKeyOnTarget: "user_id" }
- * ```
- * @group Models
- */
-export interface HasOneRelation extends RelationBase {
-    kind: "hasOne";
-    /**
-     * Column on the **target's** table holding this collection's key.
-     * Defaults to `<thisCollection>_id`.
-     */
-    foreignKeyOnTarget?: string;
-    /**
-     * Column on **this** collection's table whose value `foreignKeyOnTarget`
-     * holds. Defaults to this collection's primary key.
-     *
-     * Set it when the two sides are joined on a natural key rather than on the
-     * row id — an external identity id, a SKU, a tenant slug. See
-     * {@link HasManyRelation.sourceKey}, which this mirrors.
-     */
-    sourceKey?: string;
-}
-
-/**
- * The target holds the foreign key, and many target rows point back. The
- * children belong to this parent alone — deleting one deletes a row.
- *
- * ```ts
- * posts: { kind: "hasMany", target: () => posts, foreignKeyOnTarget: "author_id" }
- * ```
- * @group Models
- */
-export interface HasManyRelation extends RelationBase {
-    kind: "hasMany";
-    /**
-     * Column on the **target's** table holding this collection's key.
-     * Defaults to `<thisCollection>_id`.
-     */
-    foreignKeyOnTarget?: string;
-    /**
-     * Column on **this** collection's table whose value `foreignKeyOnTarget`
-     * holds. Defaults to this collection's primary key.
-     *
-     * The mirror of `localKey` on {@link BelongsToRelation}: that one names the
-     * column this side reads from, this one names the column the other side
-     * points at. Without it the pair can only be joined on the row id, which
-     * makes a natural-key link — `auth_user_id ↔ auth_user_id`, a SKU, a tenant
-     * slug — inexpressible as `hasMany`, and it has to drop to the read-only
-     * `via`.
-     *
-     * The column must be unique: the link addresses one source row per value,
-     * and Postgres will not accept a foreign key against a non-unique column.
-     *
-     * ```ts
-     * applications: {
-     *     kind: "hasMany",
-     *     target: () => talentApplications,
-     *     sourceKey: "auth_user_id",
-     *     foreignKeyOnTarget: "auth_user_id"
-     * }
-     * ```
-     */
-    sourceKey?: string;
-}
-
-/**
- * Both sides hold many, through a junction table. The target rows are shared,
- * so this collection owns the *link* and not the row: removing one removes a
- * junction row and leaves the target alone.
- *
- * Declared the same way from either side — there is no owning and inverse
- * version. Swap `sourceColumn` and `targetColumn` to describe the other
- * direction.
- *
- * ```ts
- * tags: { kind: "manyToMany", target: () => tags }
- * ```
- * @group Models
- */
-export interface ManyToManyRelation extends RelationBase {
-    kind: "manyToMany";
-    /**
-     * The junction table and its two key columns. Every part defaults: the
-     * table to both table names sorted and joined, the columns to
-     * `<collection>_id` and `<relationName>_id`.
-     */
-    through?: {
-        table?: string;
-        /** Junction column holding **this** collection's key. */
-        sourceColumn?: string;
-        /** Junction column holding the **target's** key. */
-        targetColumn?: string;
-    };
-}
-
-/**
- * An explicit chain of joins, for links the four shapes above cannot express:
- * multi-hop paths, composite keys, or a join whose condition is not a plain
- * foreign key.
- *
- * Read-only. Rebase will not infer how to write through an arbitrary join
- * chain, and guessing is what this type exists to stop.
- *
- * ```ts
- * permissions: {
- *     kind: "via",
- *     target: () => permissions,
- *     cardinality: "many",
- *     joinPath: [
- *         { table: "user_roles",       on: { from: "id",            to: "user_id" } },
- *         { table: "role_permissions", on: { from: "role_id",       to: "role_id" } },
- *         { table: "permissions",      on: { from: "permission_id", to: "id" } }
- *     ]
- * }
- * ```
- * @group Models
- */
-export interface ViaRelation extends RelationBase {
-    kind: "via";
-    /** Whether the chain yields one row or many. Cannot be derived from a join chain. */
-    cardinality: "one" | "many";
-    joinPath: JoinStep[];
-}
-
-/**
- * A link from one collection to another, as authored.
- *
- * A closed union: pick the kind that describes the link and the type offers
- * exactly the fields that kind needs. See {@link ResolvedRelation} for the form
- * the runtime works with, which has every default filled in.
- *
- * @group Models
- */
-export type Relation =
-    | BelongsToRelation
-    | HasOneRelation
-    | HasManyRelation
-    | ManyToManyRelation
-    | ViaRelation;
-
-/**
- * A relation with every default filled in — the form the runtime works with.
- *
- * The authored {@link Relation} and this are deliberately different types.
- * They used to be one, which meant no reader could tell which fields had been
- * supplied and which had been guessed, and so every consumer re-derived what it
- * needed with its own chain of `if (through) … else if (localKey) …` fallbacks.
- * Those chains disagreed with each other; that disagreement is what produced
- * silently wrong reads and corrupt writes.
- *
- * Here each variant carries exactly its own fields, all required. A consumer
- * switches on `kind` and gets what it needs without a fallback, and the cases
- * it forgot are a compile error rather than a wrong answer at runtime.
- *
- * @group Models
- */
-export type ResolvedRelation =
-    | ResolvedBelongsTo
-    | ResolvedHasOne
-    | ResolvedHasMany
-    | ResolvedManyToMany
-    | ResolvedVia;
-
-/** Fields present on every resolved relation. @group Models */
-export interface ResolvedRelationBase {
-    /** Always set: defaulted during resolution if the author omitted it. */
-    relationName: string;
-    target: () => AnyCollectionConfig;
-    /** The target's slug, resolved once so consumers need not call `target()`. */
-    targetSlug: string;
-    onUpdate?: OnAction;
-    onDelete?: OnAction;
-    overrides?: Partial<AnyCollectionConfig>;
-    validation?: { required?: boolean };
-    /**
-     * Whether one row or many come back. Derived from `kind` — kept because it
-     * is what most consumers actually branch on, and because `via` is the one
-     * kind where it is authored rather than implied.
-     */
-    cardinality: "one" | "many";
-    /**
-     * Whether Rebase knows how to write through this link. False only for
-     * {@link ResolvedVia}, whose join chain it will not invent a write for.
-     */
-    writable: boolean;
-    /**
-     * Whether the target rows are shared with other parents. True for
-     * many-to-many and for multi-hop `via`: what the parent owns is the link,
-     * so removing one must not delete the row.
-     */
-    shared: boolean;
-}
-
-/** @group Models */
-export interface ResolvedBelongsTo extends ResolvedRelationBase {
-    kind: "belongsTo";
-    cardinality: "one";
-    writable: true;
-    shared: false;
-    /** Column on this collection's table. */
-    localKey: string;
-}
-
-/** @group Models */
-export interface ResolvedHasOne extends ResolvedRelationBase {
-    kind: "hasOne";
-    cardinality: "one";
-    writable: true;
-    shared: false;
-    /** Column on the target's table. */
-    foreignKeyOnTarget: string;
-    /** @see ResolvedHasMany.sourceKey */
-    sourceKey?: string;
-}
-
-/** @group Models */
-export interface ResolvedHasMany extends ResolvedRelationBase {
-    kind: "hasMany";
-    cardinality: "many";
-    writable: true;
-    shared: false;
-    /** Column on the target's table. */
-    foreignKeyOnTarget: string;
-    /**
-     * Column on the source's table that `foreignKeyOnTarget` points at, or
-     * `undefined` for the source's primary key.
-     *
-     * The one optional field on a resolved relation, and deliberately so. Every
-     * other default is filled in here because it can be: a table name and a
-     * column name are derivable from the relation and its two endpoints alone.
-     * The primary key is not — this driver resolves it from `isId`, then the
-     * Drizzle schema, then a column named `id`, and the middle tier does not
-     * exist at resolution time.
-     *
-     * So `undefined` is a sentinel with exactly one meaning, not a field a
-     * consumer is invited to guess at. Read it through `sourceKeyField()`,
-     * which is the only place that turns it into a column name.
-     */
-    sourceKey?: string;
-}
-
-/** @group Models */
-export interface ResolvedManyToMany extends ResolvedRelationBase {
-    kind: "manyToMany";
-    cardinality: "many";
-    writable: true;
-    shared: true;
-    through: {
-        table: string;
-        sourceColumn: string;
-        targetColumn: string;
-    };
-}
-
-/** @group Models */
-export interface ResolvedVia extends ResolvedRelationBase {
-    kind: "via";
-    writable: false;
-    joinPath: JoinStep[];
-}
-
-// ── Narrowing helpers ────────────────────────────────────────────────
-//
-// Consumers that only care about one axis — "does this list many rows",
-// "is there a column on the target" — should ask that question rather
-// than enumerate kinds, so adding a kind later does not silently skip them.
-
-/** Relations whose target row carries this collection's key. @group Models */
-export type ResolvedForeignKeyOnTarget = ResolvedHasOne | ResolvedHasMany;
-
-/** @group Models */
-export function hasForeignKeyOnTarget(relation: ResolvedRelation): relation is ResolvedForeignKeyOnTarget {
-    return relation.kind === "hasOne" || relation.kind === "hasMany";
-}
-
-/** @group Models */
-export function isManyToMany(relation: ResolvedRelation): relation is ResolvedManyToMany {
-    return relation.kind === "manyToMany";
-}
-
-/** @group Models */
-export function isToMany(relation: ResolvedRelation): boolean {
-    return relation.cardinality === "many";
-}
-
-/**
- * Defines a single, explicit step in a multi-join path.
- *
- * Each step represents one JOIN operation in the sequence. The `from` columns
- * refer to the previous table in the chain (or the source table for the first step),
- * and the `to` columns refer to the current table being joined.
- *
- * @example Single column join:
- * ```typescript
- * {
- *   table: "authors",
- *   on: {
- *     from: "author_id",  // Column from previous table (e.g., posts.author_id)
- *     to: "id"           // Column from current table (authors.id)
- *   }
- * }
- * ```
- *
- * @example Multi-column composite key join:
- * ```typescript
- * {
- *   table: "order_items",
- *   on: {
- *     from: ["order_id", "store_id"],    // Multiple columns from previous table
- *     to: ["order_id", "store_id"]       // Corresponding columns in current table
- *   }
- * }
- * ```
- */
-export interface JoinStep {
-    /**
-     * The database table name to join TO in this step.
-     * This is the table you're joining into, not the table you're joining from.
-     *
-     * @example "authors", "user_roles", "product_categories"
-     */
-    table: string;
-
-    /**
-     * The join condition for this step. Defines how the previous table
-     * connects to the current table.
-     *
-     * - `from`: Column name(s) on the PREVIOUS table in the join chain
-     * - `to`: Column name(s) on the CURRENT table (specified in `table`)
-     *
-     * For the first step, `from` refers to the source collection's table.
-     * For subsequent steps, `from` refers to the table from the previous step.
-     *
-     * Both `from` and `to` support:
-     * - Single column: `"user_id"`
-     * - Multiple columns: `["company_id", "region_id"]` for composite keys
-     *
-     * When using arrays, both `from` and `to` must have the same length,
-     * and columns are matched by position (index 0 with index 0, etc.).
-     */
-    on: {
-        from: string | string[];
-        to: string | string[];
-    };
-}