@rebasepro/types 0.17.3 → 0.18.1

package/src/types/backup.ts

@@ -1,26 +0,0 @@
-/**
- * Backup type definitions shared across server, client, and studio.
- */
-
-/** Where a backup lives — a local path or an object-storage bucket. */
-export type BackupDestinationKind = "local" | "s3" | "gcs";
-
-/**
- * A single backup as surfaced by the admin API / Studio Backups panel.
- */
-export interface BackupInfo {
-    /** Storage key (object storage) or absolute file path (local). */
-    key: string;
-
-    /** Display name — the file's basename. */
-    name: string;
-
-    /** Size in bytes, when known. */
-    sizeBytes?: number;
-
-    /** ISO timestamp the backup was created, when recoverable. */
-    createdAt?: string;
-
-    /** The kind of destination this backup was read from. */
-    destinationKind: BackupDestinationKind;
-}

package/src/types/channel_bus.ts

@@ -1,202 +0,0 @@
-/**
- * The cross-instance transport for channel broadcast and presence, and the
- * contract anyone implementing one has to meet.
- *
- * These types live in `@rebasepro/types` rather than in the Postgres adapter on
- * purpose: a transport package should depend on the contract, not on the
- * database driver that happens to ship the default implementation. A
- * `@rebasepro/channel-bus-<something>` package needs this file and nothing else.
- *
- * Why a transport exists at all: entity/collection realtime already spans
- * instances (CDC, or per-mutation LISTEN/NOTIFY). Channel broadcast and presence
- * did not — they fanned out from per-process maps, so two clients served by
- * different replicas could not see each other, and nothing errored. The bus is
- * the missing hop, and deliberately *only* that hop: which local clients receive
- * a frame stays in the realtime service, so a transport never has to know what a
- * subscription, a WebSocket or a presence roster is.
- */
-
-/**
- * A frame in flight between instances.
- *
- * `sid` identifies the publishing instance. The realtime service drops frames
- * carrying its own `sid` on arrival — local fan-out already happened before the
- * publish — so a transport that echoes a publisher's own messages back to it is
- * still correct, merely wasteful.
- *
- * Keys are spelled out rather than abbreviated. The one shipped transport with a
- * size limit has a pointer path for anything that would approach it, so shaving
- * bytes off key names buys nothing worth the opacity.
- */
-export type ChannelBusFrame =
-    /** A broadcast carrying its payload. */
-    | {
-        kind: "broadcast";
-        sid: string;
-        channel: string;
-        event: string;
-        /** Originating client, echoed so receivers can skip it if it is theirs. */
-        from?: string;
-        /** Sequence number, present only on retained channels. */
-        seq?: number;
-        payload: unknown;
-    }
-    /**
-     * A broadcast too large for the transport to carry inline: the body is
-     * already durable in `rebase.channel_messages`, so the frame carries only
-     * its address and each receiver reads it back. Only ever emitted for
-     * retained channels, and only by a transport with a finite
-     * {@link ChannelBus.maxFrameBytes}.
-     */
-    | {
-        kind: "broadcast_ref";
-        sid: string;
-        channel: string;
-        from?: string;
-        seq: number;
-    }
-    /** A presence join/leave/update, small by construction. */
-    | {
-        kind: "presence_diff";
-        sid: string;
-        channel: string;
-        joins: Record<string, Record<string, unknown>>;
-        leaves: Record<string, Record<string, unknown>>;
-    };
-
-/** Receives frames published by *other* instances. */
-export type ChannelBusHandler = (frame: ChannelBusFrame) => void | Promise<void>;
-
-/**
- * A cross-instance transport.
- *
- * ## What an implementation must guarantee
- *
- * - **`start()` rejects if the transport is unusable.** The caller falls back to
- *   in-process delivery when it does. Resolving while disconnected produces a
- *   cluster that believes it is connected and silently is not, which is the
- *   exact failure this whole mechanism exists to remove.
- * - **`publish()` reaches every *other* instance, or rejects.** Delivery back to
- *   the publisher is permitted but pointless (see {@link ChannelBusFrame.sid}).
- * - **`stop()` is idempotent** and releases everything, including anything
- *   holding the event loop open.
- * - **A malformed message never throws out of the transport.** Parsing happens
- *   inside the implementation; drop and log what you cannot understand, so one
- *   bad frame cannot take the listener down.
- *
- * ## What it does *not* have to guarantee
- *
- * - **Ordering.** Retained channels carry `seq`, and the client SDK orders by
- *   it. Unsequenced broadcasts are cursor-grade traffic where order is not
- *   meaningful.
- * - **Durability.** A frame lost in transit is a missed live update; retained
- *   channels repair themselves through the client's `channel_history` replay.
- * - **Exactly-once.** Duplicates are tolerated — retained frames are deduped by
- *   `seq`, and presence diffs are idempotent by construction.
- */
-export interface ChannelBus {
-    /**
-     * Identifies the transport in logs and in `getChannelBusKind()`. Use your
-     * own name; the framework only compares against `"memory"` to decide
-     * whether publishing is worth attempting at all.
-     */
-    readonly kind: string;
-
-    /**
-     * Largest frame this transport will carry, in bytes of encoded JSON, or
-     * `Infinity` when there is no meaningful ceiling.
-     *
-     * A broadcast that exceeds it is published as a `broadcast_ref` pointer when
-     * the channel is retained, and refused with an error to the sender when it
-     * is not. Implementations with no limit should return `Infinity` rather than
-     * a large number, so the pointer path is never taken needlessly.
-     */
-    readonly maxFrameBytes: number;
-
-    /** Connect and begin delivering remote frames to `handler`. */
-    start(handler: ChannelBusHandler): Promise<void>;
-
-    /** Publish a frame to the other instances. */
-    publish(frame: ChannelBusFrame): Promise<void>;
-
-    /** Disconnect and release resources. Idempotent. */
-    stop(): Promise<void>;
-}
-
-/**
- * Which transport to use, for the two that ship with the Postgres adapter.
- *
- * To use one that does not ship here — a Redis package, or your own class —
- * pass the {@link ChannelBus} instance itself instead of a config object.
- *
- * There are deliberately only two built in, and neither adds a service to a
- * deployment. Rebase deploys as Postgres + backend + frontend; a bus that
- * required a message broker would put a second stateful service into every
- * `docker-compose.yml` the CLI scaffolds, for a feature most applications never
- * use. Measured across two backend instances against one Postgres container,
- * the Postgres bus carried ~10k cross-instance messages/second with no losses,
- * and stayed flat out to eight instances — comfortably past what live-cursor
- * collaboration generates. The extension point below is the answer for anyone
- * who does outgrow it.
- */
-export type ChannelBusConfig =
-    /**
-     * In-process only — the historical behaviour. Broadcast and presence reach
-     * the clients connected to *this* instance and no further.
-     */
-    | { type: "memory" }
-    /**
-     * Postgres LISTEN/NOTIFY, reusing infrastructure the deployment already has.
-     *
-     * `pg_notify` caps a payload at 8000 bytes, so a broadcast larger than that
-     * is delivered cross-instance only on a *retained* channel, where the
-     * notification carries a pointer (`seq`) instead of the message and each
-     * receiver reads the body back from `rebase.channel_messages`. An oversized
-     * broadcast on an ephemeral channel is refused rather than silently
-     * delivered to half the cluster.
-     *
-     * NOTE: `LISTEN` needs a session-mode connection. Behind PgBouncer in
-     * transaction mode this must point at the database directly
-     * (`DATABASE_DIRECT_URL`), not at the pooler.
-     */
-    | {
-        type: "postgres";
-        /** Direct connection for the LISTEN client. Defaults to `DATABASE_DIRECT_URL`. */
-        connectionString?: string;
-        /**
-         * How long to coalesce outgoing frames into a single notification, in
-         * milliseconds. Defaults to 10.
-         *
-         * A notify is a query on your primary database, so under load this is
-         * the difference between one query per message and one per window. The
-         * window is leading-edge: a frame arriving when none is open goes out
-         * immediately, so an idle channel pays no added latency and only a
-         * sustained stream is batched.
-         *
-         * Set to 0 to disable coalescing and send every frame on its own.
-         */
-        batchWindowMs?: number;
-    };
-
-/**
- * What `realtime.bus` accepts: a built-in transport by name, or any
- * {@link ChannelBus} instance.
- *
- * ```typescript
- * realtime: { bus: { type: "postgres" } }        // shipped
- * realtime: { bus: new MyRedisChannelBus(url) }  // a separate package, or your own
- * ```
- */
-export type ChannelBusSetting = ChannelBusConfig | ChannelBus;
-
-/**
- * Whether `setting` is an already-constructed transport rather than a request
- * for a built-in one.
- *
- * Structural rather than nominal so that an instance from a *different copy* of
- * `@rebasepro/types` — an entirely normal outcome of a separately versioned
- * transport package — is still recognised.
- */
-export function isChannelBusInstance(setting: ChannelBusSetting | undefined): setting is ChannelBus {
-    return typeof (setting as ChannelBus | undefined)?.publish === "function";
-}

package/src/types/chips.ts

@@ -1,34 +0,0 @@
-export type ColorScheme = {
-    color: string;
-    text: string;
-}
-
-/**
- * The hues a chip can take.
- *
- * Kept in step with `CHIP_HUES` in `@rebasepro/ui` by hand: config types cannot
- * depend on the component library. A hue added there needs adding here too.
- */
-export type ColorHue =
-    | "blue"
-    | "cyan"
-    | "teal"
-    | "green"
-    | "yellow"
-    | "orange"
-    | "red"
-    | "pink"
-    | "purple"
-    | "gray"
-    | "indigo"
-    | "violet"
-    | "fuchsia"
-    | "rose"
-    | "emerald";
-
-/**
- * How light or saturated a chip is. A hue on its own means `Lighter`.
- */
-export type ColorTone = "Lighter" | "Light" | "Dark" | "Darker";
-
-export type ColorKey = ColorHue | `${ColorHue}${ColorTone}`;

package/src/types/collection_contract.ts

@@ -1,278 +0,0 @@
-import type { CollectionConfig } from "./collections";
-
-/**
- * Serializing collections so they survive a network hop.
- *
- * A collection definition is not plain data. Relations point at their target
- * with a *function* (`target: () => usersCollection`) so two collections can
- * reference each other without an import cycle, and collections also carry
- * callbacks, custom views and component references. `JSON.stringify` silently
- * drops every one of those, which matters because the SDK generator *calls*
- * `relation.target()` to decide whether a foreign key is a string or a number.
- * Serialize naively and remote SDK generation produces subtly wrong types
- * instead of failing — the worst possible outcome.
- *
- * So relation targets are resolved to a slug reference on the way out and
- * rebuilt into functions on the way in. Everything else that cannot cross a wire
- * is dropped deliberately: an SDK is generated from the *shape* of the data, and
- * server-side behaviour is neither useful to a client nor safe to publish.
- */
-
-/** Marker replacing a relation's `target` function in serialized form. */
-export interface SerializedCollectionRef {
-    __collectionRef: string;
-}
-
-export function isSerializedCollectionRef(value: unknown): value is SerializedCollectionRef {
-    return typeof value === "object"
-        && value !== null
-        && typeof (value as SerializedCollectionRef).__collectionRef === "string";
-}
-
-/** Depth limit for the walk — deep enough for real configs, finite for cyclic ones. */
-const MAX_DEPTH = 64;
-
-/**
- * Resolve whatever a `target` thunk returns down to a collection.
- *
- * A target may be the collection, a module namespace (when the authoring file
- * used `import * as`), or a default-export wrapper. All three appear in real
- * projects, and the SDK generator already unwraps them the same way.
- */
-function unwrapTarget(value: unknown): CollectionConfig | undefined {
-    if (!value || typeof value !== "object") return undefined;
-    const candidate = value as { default?: unknown; __esModule?: boolean; properties?: unknown };
-    if (candidate.default || candidate.__esModule) {
-        const inner = candidate.default;
-        if (inner && typeof inner === "object") return inner as CollectionConfig;
-    }
-    if (candidate.properties) return value as CollectionConfig;
-    return undefined;
-}
-
-/** The identity a serialized reference uses. Slug first — it is the routing key. */
-function refFor(collection: CollectionConfig | undefined): string | undefined {
-    if (!collection) return undefined;
-    const withPath = collection as CollectionConfig & { path?: string };
-    return collection.slug || withPath.path || collection.name;
-}
-
-/**
- * Deep-copy a value into something JSON can carry.
- *
- * `target` keys are special-cased into refs. Other functions vanish, cycles are
- * cut, and everything else is copied structurally.
- */
-/** Shared walk state: the memo, plus a count of depth-cap hits. */
-interface WalkState {
-    memo: WeakMap<object, unknown>;
-    /**
-     * How many times the walk has truncated a subtree — by hitting the depth
-     * cap, or by cutting a cycle.
-     *
-     * Either kind of truncation makes a result valid only at the *position* it
-     * was produced at, so caching it and serving it elsewhere silently drops
-     * content that would have been included. Comparing this counter before and
-     * after a node's children tells us whether its result is position-
-     * independent and therefore safe to memoize.
-     *
-     * The cycle case is the subtle one: with `a.b = b` and `b.a = a`, serializing
-     * `{ first: b, second: a }` visits `a` beneath `b` — where the cycle back to
-     * `b` is cut — and would then reuse that truncated `a` for `second`, where
-     * nothing needed cutting.
-     */
-    truncations: number;
-}
-
-function toSerializable(
-    value: unknown,
-    seen: WeakSet<object>,
-    depth: number,
-    state: WalkState,
-    key?: string
-): unknown {
-    if (depth > MAX_DEPTH) {
-        state.truncations++;
-        return undefined;
-    }
-
-    if (typeof value === "function") {
-        // Only a relation target carries information a client needs. Calling it
-        // is safe here — this runs on the server, where the target module is
-        // already loaded — and a throwing target simply yields no reference,
-        // which degrades the generated FK type rather than failing the request.
-        if (key === "target") {
-            try {
-                const resolved = unwrapTarget((value as () => unknown)());
-                const ref = refFor(resolved);
-                return ref ? { __collectionRef: ref } : undefined;
-            } catch {
-                return undefined;
-            }
-        }
-        return undefined;
-    }
-
-    if (value === null || typeof value !== "object") {
-        return value;
-    }
-
-    if (value instanceof Date) return value.toISOString();
-    if (value instanceof RegExp) return value.source;
-
-    if (seen.has(value as object)) {
-        state.truncations++;
-        return undefined;
-    }
-
-    // A shared (non-cyclic) subgraph is reachable by many paths, and `seen` is a
-    // *path* set — released in the `finally` below so a node referenced twice in
-    // different branches is emitted twice rather than dropped as a false cycle.
-    // Without memoization that makes the walk exponential in depth: a diamond
-    // graph 20 levels deep took ~400ms, and each further level doubled it. The
-    // result is a plain data tree, so handing back the same converted object for
-    // a repeat visit is indistinguishable after JSON.stringify.
-    const cached = state.memo.get(value as object);
-    if (cached !== undefined) return cached;
-
-    seen.add(value as object);
-    const truncationsBefore = state.truncations;
-    const memoize = (result: unknown): unknown => {
-        // Only cache a result that nothing was cut from.
-        if (result !== undefined && state.truncations === truncationsBefore) {
-            state.memo.set(value as object, result);
-        }
-        return result;
-    };
-
-    try {
-        if (Array.isArray(value)) {
-            const items = value
-                .map(item => toSerializable(item, seen, depth + 1, state))
-                .filter(item => item !== undefined);
-            // A container that had content, none of which can be represented, is
-            // itself unrepresentable — see the note below.
-            return memoize(value.length > 0 && items.length === 0 ? undefined : items);
-        }
-
-        // A React element or component reference has no meaning to a client and
-        // will not survive JSON anyway.
-        if ("$$typeof" in (value as Record<string, unknown>)) return undefined;
-
-        const entries = Object.entries(value as Record<string, unknown>);
-        const out: Record<string, unknown> = {};
-        for (const [k, v] of entries) {
-            const converted = toSerializable(v, seen, depth + 1, state, k);
-            if (converted !== undefined) out[k] = converted;
-        }
-
-        // Drop a container whose entire content was dropped.
-        //
-        // `callbacks: { beforeSave() {…} }` would otherwise serialize to
-        // `callbacks: {}` — an empty husk that carries no information but is not
-        // *nothing*, so it lands in the payload and, worse, in the schema hash.
-        // Editing a hook would then change every client's schema version and
-        // report perfectly current SDKs as stale.
-        //
-        // A container that started empty stays empty: `properties: {}` is a
-        // deliberate statement, not a casualty.
-        if (entries.length > 0 && Object.keys(out).length === 0) return undefined;
-
-        return memoize(out);
-    } finally {
-        // Released so a collection referenced twice in different branches is
-        // emitted twice rather than being dropped as a false cycle.
-        seen.delete(value as object);
-    }
-}
-
-/**
- * Serialize collections for transport over the contract endpoint.
- *
- * Sorted by slug so the output — and therefore the schema hash computed from it
- * — does not depend on filesystem ordering.
- */
-export function serializeCollections(collections: CollectionConfig[]): unknown[] {
-    return [...collections]
-        .sort((a, b) => String(a.slug ?? "").localeCompare(String(b.slug ?? "")))
-        .map(collection => toSerializable(withoutAdminBlock(collection), new WeakSet(), 0, {
-            memo: new WeakMap(),
-            truncations: 0
-        }))
-        .filter((c): c is Record<string, unknown> => c !== undefined);
-}
-
-/**
- * Drop the admin block before the walk.
- *
- * Nothing downstream of serialization is an admin panel. The contract endpoint
- * feeds remote SDK generation, and `rebase build` writes the result into a bundle
- * manifest that only the backend runtime reads. The block would survive the walk
- * as a husk anyway — its React elements and component functions are dropped
- * individually — and that husk has two costs worth avoiding: it puts every custom
- * component's *file path* on an endpoint whose job is to describe data shapes, and
- * it grows a payload that is fetched and cached per project.
- *
- * Removing it here rather than at each call site means one chokepoint, so a future
- * consumer of `serializeCollections` cannot forget.
- *
- * Child collections carry their own block, so this recurses — stripping only the
- * top level was the mistake `stripNonClientFields` in the contract routes already
- * had to fix once for security rules.
- */
-function withoutAdminBlock(collection: CollectionConfig): CollectionConfig {
-    const { admin: _admin, ...rest } = collection as CollectionConfig & Record<string, unknown>;
-    const nested = rest as Record<string, unknown>;
-    if (Array.isArray(nested.subcollections)) {
-        nested.subcollections = nested.subcollections.map(
-            (child) => withoutAdminBlock(child as CollectionConfig)
-        );
-    }
-    return rest as CollectionConfig;
-}
-
-/**
- * Rebuild collections received from a contract endpoint.
- *
- * Relation refs become real thunks resolving through the returned set, so
- * downstream consumers — the SDK generator above all — see exactly the shape
- * they would have seen had the collections been imported from source.
- *
- * A ref naming a collection that is not in the payload resolves to `undefined`
- * rather than throwing: the generator already tolerates an unresolvable target
- * by falling back to a permissive key type, and a partial contract should still
- * produce a usable SDK.
- */
-export function deserializeCollections(payload: unknown[]): CollectionConfig[] {
-    const collections = payload
-        .filter((c): c is Record<string, unknown> => typeof c === "object" && c !== null)
-        .map(c => ({ ...c })) as unknown as CollectionConfig[];
-
-    const bySlug = new Map<string, CollectionConfig>();
-    for (const collection of collections) {
-        const ref = refFor(collection);
-        if (ref) bySlug.set(ref, collection);
-    }
-
-    const rehydrate = (value: unknown, depth: number): void => {
-        if (depth > MAX_DEPTH || !value || typeof value !== "object") return;
-
-        if (Array.isArray(value)) {
-            for (const item of value) rehydrate(item, depth + 1);
-            return;
-        }
-
-        const record = value as Record<string, unknown>;
-        for (const [key, child] of Object.entries(record)) {
-            if (key === "target" && isSerializedCollectionRef(child)) {
-                const slug = child.__collectionRef;
-                record.target = () => bySlug.get(slug);
-                continue;
-            }
-            rehydrate(child, depth + 1);
-        }
-    };
-
-    for (const collection of collections) rehydrate(collection, 0);
-    return collections;
-}