@rebasepro/types 0.17.3 → 0.18.1

package/src/types/component_ref.ts

@@ -1,92 +0,0 @@
-/**
- * How a collection points at a UI component without the backend learning about React.
- *
- * This file is the hinge the BaaS/admin split turns on. `ComponentRef` is named
- * by a property's `admin` block (`admin.Field`, `admin.Preview`, `admin.Filter`)
- * and imported by `properties.ts`, which must stay in the React-free core
- * because every backend subsystem — validation,
- * the drizzle schema generator, the OpenAPI generator, the SDK codegen — reads
- * property definitions. If `ComponentRef` needed `React.ComponentType`, the whole
- * property model would have to move to the admin layer with it.
- *
- * So the React types are described structurally instead of imported. Every form
- * a React component takes is assignable to {@link ComponentLike}:
- *
- * - a function component is `(props: P) => ReactNode`
- * - a class component satisfies the construct signature (`Component` has `render`)
- * - `memo` and `forwardRef` return exotic components, which are callable
- *
- * The cost is that the return type is `unknown` rather than `ReactNode`, so a
- * function that returns something React could not render is accepted here.
- * `@rebasepro/cms-types` re-exports a `ReactComponentRef<P>` narrowed against
- * the real `React.ComponentType` for authoring and for the admin's internals,
- * which restores that check where it can be enforced.
- */
-
-/**
- * Structural stand-in for `React.ComponentType<P>`.
- *
- * Deliberately not `Function` or `unknown`: those would accept anything and the
- * resolver's runtime heuristics ({@link ComponentRef} form 3) would be all that
- * stood between a typo and a blank screen.
- */
-export type ComponentLike<P = any> =
-    | ((props: P) => unknown)
-    | (new (props: P, context?: unknown) => { render(): unknown });
-
-/**
- * Internal marker for a lazily-loaded component reference.
- * Created by the Vite transform plugin when converting string paths
- * to deferred `import()` calls. Users should NOT create these manually.
- *
- * @internal
- */
-export interface LazyComponentRef<P = unknown> {
-    readonly __rebaseLazy: true;
-    readonly load: () => Promise<{ default: ComponentLike<P> }>;
-}
-
-/**
- * A reference to a UI component that can be provided in three forms:
- *
- * 1. **String path** (recommended for collection configs):
- *    ```ts
- *    Field: "../../frontend/src/components/MyField"
- *    ```
- *    The Vite plugin transforms this into a `LazyComponentRef` at build time.
- *    On the backend, the string stays inert and is never evaluated.
- *
- * 2. **Lazy import function**:
- *    ```ts
- *    Field: () => import("../../frontend/src/components/MyField")
- *    ```
- *    Standard ES dynamic import. Backend never calls the function.
- *
- * 3. **Direct component reference** (use only in frontend-only code):
- *    ```ts
- *    Field: MyFieldComponent
- *    ```
- *    Importing a component at the top level will pull React into the
- *    backend runtime — only safe in code that the backend never imports.
- *    `pnpm check:headless` fails on a collection file that does this.
- *
- * @group Types
- */
-export type ComponentRef<P = any> =
-    | string
-    | LazyComponentRef<P>
-    | (() => Promise<{ default: ComponentLike<P> }>)
-    | ComponentLike<P>;
-
-/**
- * Type guard: checks if a value is a `LazyComponentRef` produced by the
- * Vite transform plugin.
- */
-export function isLazyComponentRef<P = unknown>(ref: unknown): ref is LazyComponentRef<P> {
-    return (
-        typeof ref === "object" &&
-        ref !== null &&
-        "__rebaseLazy" in ref &&
-        (ref as Record<string, unknown>).__rebaseLazy === true
-    );
-}

package/src/types/cron.ts

@@ -1,213 +0,0 @@
-import type { RebaseServerClient } from "../controllers/client";
-
-/**
- * Cron Job type definitions for Rebase.
- *
- * These types define the shape of cron job definitions, their runtime
- * status, and execution log entries — used across server, client,
- * and studio packages.
- */
-
-// =============================================================================
-// CRON JOB DEFINITION (static, declared by the developer)
-// =============================================================================
-
-/**
- * A cron job definition file exports this shape as its default export.
- * See the example cron files in `app/backend/crons/` for usage.
- */
-export interface CronJobDefinition {
-    // Cron schedule expression, e.g. "0 3 * * *" for daily at 3 AM.
-    schedule: string;
-
-    /** Human-readable name shown in the Studio UI. */
-    name: string;
-
-    /** Optional description shown in the Studio UI. */
-    description?: string;
-
-    /**
-     * Whether the job is enabled at startup. Defaults to `true`.
-     * Can be toggled at runtime via the Admin API.
-     */
-    enabled?: boolean;
-
-    /**
-     * Maximum number of seconds the handler may run before being
-     * considered timed-out. Default: 300 (5 min).
-     */
-    timeoutSeconds?: number;
-
-    /**
-     * How far back to look, on startup, for a slot that elapsed while no
-     * instance was holding a timer for it. Off by default.
-     *
-     * The scheduler drives jobs with in-process `setTimeout` and computes the
-     * next slot from *now* on every boot, so a slot only fires if some instance
-     * happened to be alive and ticking when it came round. That is not a
-     * scale-to-zero problem: a platform that recycles containers — Cloud Run
-     * rotating an instance under `--min-instances 1`, a rolling deploy, a crash
-     * loop — drops any slot that falls inside the changeover, and the
-     * replacement schedules the slot *after* it. The run is skipped in silence.
-     *
-     * Set this to a window comfortably wider than a restart (a few minutes for
-     * a frequent job; an hour or more for a daily one) and startup will run a
-     * slot it finds unclaimed inside that window.
-     *
-     * Two deliberate limits:
-     *
-     * - **Only the most recent missed slot runs.** Booting after a six-hour
-     *   outage catches an hourly job up once, not six times. Catch-up exists to
-     *   stop a run going missing, not to replay history.
-     * - **A claims-capable store is required.** Catch-up is skipped entirely
-     *   when the store has no `tryClaimRun` (or no store is attached), because
-     *   the claim is the only thing that distinguishes "this slot never ran"
-     *   from "this slot already ran on the instance I am replacing". Without
-     *   it, an instance recycled every 30 minutes would re-run the same hourly
-     *   job every time it booted.
-     *
-     * @example catchUpWindowSeconds: 3600  // daily job: tolerate an hour of downtime
-     */
-    catchUpWindowSeconds?: number;
-
-    /**
-     * The handler function executed on each tick.
-     * Receives a context object with the data driver and logger.
-     * May return arbitrary JSON-serialisable data stored in the log.
-     */
-    handler: (ctx: CronJobContext) => Promise<unknown> | unknown;
-}
-
-
-/**
- * Context passed to each cron handler invocation.
- */
-export interface CronJobContext {
-    /** The job's unique ID (derived from filename). */
-    jobId: string;
-
-    /** The current scheduled tick timestamp. */
-    scheduledAt: Date;
-
-    /** A simple logger scoped to this job run. */
-    log: (...args: unknown[]) => void;
-
-    /**
-     * The server-side Rebase singleton — the **same object** `import { rebase }
-     * from "@rebasepro/server"` returns, and the same one `defineFunction`
-     * hands its callback. Spelled the same way here so that one thing has one
-     * name across every server-side authoring surface.
-     *
-     * Its data plane is {@link RebaseServerClient.dataAsAdmin}, scoped as
-     * `{ uid: "service", roles: ["admin"] }` — **admin-scoped, not
-     * RLS-bypassing**. Statements still run as `rebase_user` with the policies
-     * evaluated against that identity; the admin role merely clears the default
-     * policies through their `rolesOverlap(['admin'])` arm, and
-     * `policy.serverContext()` (`rebase.uid() IS NULL`) is *false* for it.
-     * `rebase.sql()` is the unconditional bypass. A cron has no per-request
-     * user, so there is no user-scoped alternative here: scope every query's
-     * filters yourself.
-     *
-     * @example
-     * export default defineCron({
-     *     name: "Nightly cleanup",
-     *     schedule: "0 3 * * *",
-     *     async handler({ rebase, log }) {
-     *         const expired = await rebase.dataAsAdmin.sessions.findAll({
-     *             where: { expired: ["==", true] }
-     *         });
-     *         for (const session of expired) {
-     *             await rebase.dataAsAdmin.sessions.delete(session.id as string);
-     *         }
-     *         log(`Deleted ${expired.length} expired sessions`);
-     *     }
-     * });
-     */
-    rebase: RebaseServerClient;
-
-}
-
-// =============================================================================
-// CRON JOB RUNTIME STATUS (what the API returns)
-// =============================================================================
-
-export type CronJobRunState = "idle" | "running" | "success" | "error" | "disabled";
-
-/**
- * Full runtime information about a registered cron job.
- */
-export interface CronJobStatus {
-    /** Unique identifier (derived from filename, e.g. "cleanup-sessions"). */
-    id: string;
-
-    /** Human-readable name from the definition. */
-    name: string;
-
-    /** Description from the definition. */
-    description?: string;
-
-    /** The cron schedule expression. */
-    schedule: string;
-
-    /** Whether the job is currently enabled. */
-    enabled: boolean;
-
-    /** Current run state. */
-    state: CronJobRunState;
-
-    /** ISO timestamp of the last execution start. */
-    lastRunAt?: string;
-
-    /** ISO timestamp of the next scheduled execution. */
-    nextRunAt?: string;
-
-    /** Duration of the last run in milliseconds. */
-    lastDurationMs?: number;
-
-    /** Error message from the last failed run. */
-    lastError?: string;
-
-    /** Total number of executions since server start. */
-    totalRuns: number;
-
-    /** Total number of failed executions since server start. */
-    totalFailures: number;
-}
-
-// =============================================================================
-// CRON JOB LOG ENTRY
-// =============================================================================
-
-export type CronLogLevel = "info" | "error" | "warn";
-
-/**
- * A single execution log entry stored in the in-memory ring buffer.
- */
-export interface CronJobLogEntry {
-    /** The job ID this log belongs to. */
-    jobId: string;
-
-    /** ISO timestamp when execution started. */
-    startedAt: string;
-
-    /** ISO timestamp when execution finished. */
-    finishedAt: string;
-
-    /** Duration in milliseconds. */
-    durationMs: number;
-
-    /** Whether this run succeeded. */
-    success: boolean;
-
-    /** Error message if the run failed. */
-    error?: string;
-
-    /** Arbitrary result data returned by the handler. */
-    result?: unknown;
-
-    /** Captured log lines. */
-    logs: string[];
-
-    /** Whether this was a manual trigger. */
-    manual?: boolean;
-}

package/src/types/data_source.ts

@@ -1,357 +0,0 @@
-import { ALL_WHERE_FILTER_OPS, WhereFilterOp } from "./filter-operators";
-
-/**
- * Describes the capabilities and features supported by a data source (driver).
- *
- * Each driver (Postgres, Firebase, MongoDB, etc.) declares which features it
- * supports. The admin uses this descriptor to:
- * - Show/hide editor tabs (e.g. Relations for SQL, Subcollections for Firebase)
- * - Filter the property type picker (e.g. `relation` for SQL, `reference` for Firebase)
- * - Toggle driver-specific form controls (e.g. `columnType` for SQL)
- *
- * @group Models
- */
-export interface DataSourceCapabilities {
-    /** Unique driver key (e.g. "postgres", "firestore", "mongodb") */
-    key: string;
-
-    /** Human-readable label for the UI (e.g. "PostgreSQL", "Firebase / Firestore") */
-    label: string;
-
-    // ── Feature flags ─────────────────────────────────────────────────
-    /** Does this source support SQL-style relations (JOINs)? */
-    supportsRelations: boolean;
-
-    /** Does this source support nested subcollections? */
-    supportsSubcollections: boolean;
-
-    /** Does this source support Row Level Security policies? */
-    supportsRLS: boolean;
-
-    /** Does this source support document references (Firebase-style)? */
-    supportsReferences: boolean;
-
-    /** Does this source support SQL column type annotations? */
-    supportsColumnTypes: boolean;
-
-    /** Does this source support real-time listeners? */
-    supportsRealtime: boolean;
-
-    /**
-     * Does this source store vectors natively?
-     *
-     * `VectorProperty` carries a `dimensions` and is pgvector-shaped. It was
-     * the one driver-specific property kind with no flag to gate it, so unlike
-     * every other field in this descriptor there was not even a runtime answer
-     * to appeal to — a Firestore collection could declare an embedding column
-     * and no driver would do anything with it.
-     */
-    supportsVectors: boolean;
-
-    /**
-     * Canonical filter operators this engine can execute.
-     *
-     * The admin UI intersects this set with the property-type defaults and
-     * any per-property narrowing (`property.ui.filterOperators`) to decide
-     * which operators to offer in filter fields — so an engine that cannot
-     * run `ilike` (e.g. Firestore) never shows a "Contains" filter that
-     * would throw at query time.
-     */
-    filterOperators: readonly WhereFilterOp[];
-
-    /**
-     * Relation kinds this engine's driver can compile into a filter.
-     *
-     * Only `belongsTo` puts a column on the row being filtered; the others are
-     * answered with a correlated subquery over the junction or the target
-     * table, which not every driver can build. An engine with no relations at
-     * all declares none.
-     *
-     * The admin uses this to decide whether a relation column offers a filter
-     * control. Offering one an engine cannot answer is not cosmetic: a driver
-     * that drops the key it cannot resolve *widens* the read to every row, and
-     * one that fails closed answers a control the admin itself put on screen
-     * with a 400.
-     *
-     * Optional, so a third-party driver registered before this existed still
-     * compiles. Omitted means {@link DEFAULT_FILTERABLE_RELATION_KINDS} — the
-     * one kind that is a plain column comparison, which every relational
-     * driver can do. The subquery kinds are a real capability and have to be
-     * claimed rather than assumed: assuming them wrongly is the widening.
-     */
-    filterableRelationKinds?: readonly string[];
-
-    /**
-     * Can a filter address a *column of the related row* — `applications.status`
-     * — rather than only the related row's id?
-     *
-     * A separate capability from {@link filterableRelationKinds} because it is
-     * a separate subquery: the id filter stops at the junction, one of these
-     * reaches the target table and compares one of its columns. A driver can
-     * do the first and not the second.
-     *
-     * Optional and defaulting to **false**, for the reason the relation kinds
-     * default narrow: an unclaimed capability that the admin assumes is there
-     * produces a control whose query the driver answers by dropping the key —
-     * and a dropped filter key widens the read to every row.
-     *
-     * Meaningless without {@link supportsRelations}; a driver with no relations
-     * has nothing to reach through.
-     */
-    supportsRelationFieldFilters?: boolean;
-
-    /**
-     * Can a sort key be an aggregate over a to-many relation — "oldest waiting
-     * first", "busiest first"?
-     *
-     * Compiled as a correlated scalar subquery in `ORDER BY`, which a document
-     * store cannot express at all. Optional and defaulting to **false**.
-     *
-     * A wrongly claimed sort capability fails differently from a wrongly
-     * claimed filter one, and worse in one respect: a driver that cannot
-     * resolve the key drops the `ORDER BY` and answers 200 with rows in
-     * whatever order the database pleased, which reads as a sorted list. Paging
-     * over that repeats and skips rows.
-     */
-    relationAggregateSorts?: boolean;
-
-    // ── Admin capability flags ───────────────────────────────────────
-    /** Does this source support SQL admin operations (SQL editor, EXPLAIN, etc.)? */
-    supportsSQLAdmin: boolean;
-
-    /** Does this source support document admin operations (aggregation, stats)? */
-    supportsDocumentAdmin: boolean;
-
-    /** Does this source support schema admin (unmapped tables, table metadata)? */
-    supportsSchemaAdmin: boolean;
-}
-
-/**
- * Subset of DataSourceCapabilities containing only feature flags.
- * Useful when you only need to check capabilities without UI metadata.
- * @group Models
- */
-export type DataSourceFeatures = Omit<DataSourceCapabilities, "key" | "label">;
-
-/**
- * The default data-source key, used when a collection does not name a
- * `dataSource`. Shared by the frontend router and the backend driver
- * registry so both agree on "the default database".
- * @group Models
- */
-export const DEFAULT_DATA_SOURCE_KEY = "(default)";
-
-/**
- * How the *frontend* reaches a data source.
- *
- * - `"server"` — through the Rebase backend (the `RebaseClient`). The backend
- *   holds the actual database adapter and routes by data-source key. This is
- *   the default and covers Postgres, MongoDB, and any other server-mediated
- *   engine.
- * - `"direct"` — straight from the client to the external backend via its own
- *   SDK driver (e.g. Firestore). The Rebase backend is not in the data path.
- * - `"custom"` — a developer-supplied {@link DataDriver}, transport unspecified.
- *
- * @group Models
- */
-export type DataSourceTransport = "server" | "direct" | "custom";
-
-/**
- * Declarative definition of a data source — a named place data lives.
- *
- * Declared once and shared front and back: the frontend uses it to decide
- * transport (client vs direct driver), the backend uses the same `key` to
- * resolve a database adapter, and the editor derives capabilities from
- * `engine`. Collections reference a definition by its `key` via
- * `collection.dataSource`.
- *
- * @group Models
- */
-export interface DataSourceDefinition {
-    /**
-     * Unique identifier for this data source. Collections point at it via
-     * `dataSource`. Defaults to {@link DEFAULT_DATA_SOURCE_KEY}.
-     */
-    key: string;
-
-    /**
-     * The engine backing this data source (e.g. `"postgres"`, `"mongodb"`,
-     * `"firestore"`, or a custom id). Determines the
-     * {@link DataSourceCapabilities} surfaced in the editor.
-     */
-    engine: string;
-
-    /**
-     * How the frontend reaches this source. Optional — when omitted it is
-     * inferred: `"direct"` if the definition carries a client-side driver,
-     * `"server"` otherwise.
-     */
-    transport?: DataSourceTransport;
-
-    /**
-     * The physical database/schema/Firestore-database within the engine.
-     * Threaded to drivers/adapters as the existing `databaseId` runtime
-     * parameter. Defaults to the engine's own default.
-     */
-    databaseId?: string;
-
-    /** Human-readable label for the UI. */
-    label?: string;
-}
-
-/**
- * The resolved data source for a collection: the single source of truth that
- * the frontend router, backend registry, and editor all derive from.
- * Produced by `resolveDataSource(collection, registry)`.
- *
- * @group Models
- */
-export interface ResolvedDataSource {
-    /** Data-source key (routing key, shared front + back). */
-    key: string;
-    /** Engine backing the source (drives capabilities). */
-    engine: string;
-    /** Frontend transport. */
-    transport: DataSourceTransport;
-    /** Within-engine instance, if any (the `databaseId` runtime param). */
-    databaseId?: string;
-    /** Capabilities derived from {@link engine}. */
-    capabilities: DataSourceCapabilities;
-}
-
-/**
- * Relation kinds assumed filterable when a driver does not say.
- *
- * `belongsTo` alone: its filter is a comparison on a column of the row being
- * filtered, the one shape that needs no query construction a driver might not
- * have. Everything else is a correlated subquery over another table.
- *
- * @group Models
- */
-export const DEFAULT_FILTERABLE_RELATION_KINDS: readonly string[] = ["belongsTo"];
-
-// ── Built-in driver capabilities ─────────────────────────────────────
-
-/** @group Models */
-export const POSTGRES_CAPABILITIES: DataSourceCapabilities = {
-    key: "postgres",
-    label: "PostgreSQL",
-    supportsRelations: true,
-    supportsSubcollections: false,
-    supportsRLS: true,
-    supportsReferences: false,
-    supportsColumnTypes: true,
-    supportsRealtime: true,
-    supportsVectors: true,
-    filterOperators: ALL_WHERE_FILTER_OPS,
-    // `via` is absent: its join path is authored source → target with no
-    // stated inverse, so the driver has nothing to reverse into a filter.
-    filterableRelationKinds: ["belongsTo", "manyToMany", "hasMany", "hasOne"],
-    supportsRelationFieldFilters: true,
-    relationAggregateSorts: true,
-    supportsSQLAdmin: true,
-    supportsDocumentAdmin: false,
-    supportsSchemaAdmin: true
-};
-
-/** @group Models */
-export const FIREBASE_CAPABILITIES: DataSourceCapabilities = {
-    key: "firestore",
-    label: "Firebase / Firestore",
-    supportsRelations: false,
-    supportsSubcollections: true,
-    supportsRLS: false,
-    supportsReferences: true,
-    supportsColumnTypes: false,
-    supportsRealtime: true,
-    supportsVectors: false,
-    // Firestore has no SQL pattern matching — the driver throws on the LIKE
-    // family, so the UI must never offer it.
-    filterOperators: ALL_WHERE_FILTER_OPS.filter(op =>
-        op !== "like" && op !== "ilike" && op !== "not-like" && op !== "not-ilike"),
-    // No relations at all — a document store links by reference. Nothing to
-    // reach through, so neither of the two relation-reaching features either.
-    filterableRelationKinds: [],
-    supportsRelationFieldFilters: false,
-    relationAggregateSorts: false,
-    supportsSQLAdmin: false,
-    supportsDocumentAdmin: false,
-    supportsSchemaAdmin: false
-};
-
-/** @group Models */
-export const MONGODB_CAPABILITIES: DataSourceCapabilities = {
-    key: "mongodb",
-    label: "MongoDB",
-    supportsRelations: false,
-    supportsSubcollections: true,
-    supportsRLS: false,
-    supportsReferences: true,
-    supportsColumnTypes: false,
-    supportsRealtime: false,
-    supportsVectors: false,
-    filterOperators: ALL_WHERE_FILTER_OPS,
-    filterableRelationKinds: [],
-    supportsRelationFieldFilters: false,
-    relationAggregateSorts: false,
-    supportsSQLAdmin: false,
-    supportsDocumentAdmin: true,
-    supportsSchemaAdmin: true
-};
-
-/**
- * Fallback capabilities when the driver is unknown.
- * Enables everything so nothing is hidden unexpectedly.
- * @group Models
- */
-export const DEFAULT_CAPABILITIES: DataSourceCapabilities = {
-    key: "(default)",
-    label: "Default",
-    supportsRelations: true,
-    supportsSubcollections: true,
-    supportsRLS: true,
-    supportsReferences: true,
-    supportsColumnTypes: true,
-    supportsRealtime: true,
-    supportsVectors: true,
-    filterOperators: ALL_WHERE_FILTER_OPS,
-    // The exception to this descriptor's "enable everything" rule. The other
-    // flags hide a tab or a picker when they are wrong; this one decides
-    // whether a query is sent that an unknown driver may answer by dropping
-    // the condition — which returns every row rather than none.
-    filterableRelationKinds: DEFAULT_FILTERABLE_RELATION_KINDS,
-    // Narrow for the same reason, and more sharply. An unknown driver that is
-    // assumed to compile these answers by dropping the key: the filter widens
-    // the read to every row, and the sort comes back unordered while looking
-    // sorted. Both have to be claimed.
-    supportsRelationFieldFilters: false,
-    relationAggregateSorts: false,
-    supportsSQLAdmin: true,
-    supportsDocumentAdmin: true,
-    supportsSchemaAdmin: true
-};
-
-const CAPABILITIES_REGISTRY: Record<string, DataSourceCapabilities> = {
-    postgres: POSTGRES_CAPABILITIES,
-    firestore: FIREBASE_CAPABILITIES,
-    mongodb: MONGODB_CAPABILITIES,
-    "(default)": DEFAULT_CAPABILITIES
-};
-
-/**
- * Look up capabilities for a given engine key.
- * If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
- * @group Models
- */
-export function getDataSourceCapabilities(engine?: string): DataSourceCapabilities {
-    if (!engine) return POSTGRES_CAPABILITIES; // postgres is the default engine
-    return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;
-}
-
-/**
- * Register custom capabilities for a third-party driver.
- * @group Models
- */
-export function registerDataSourceCapabilities(capabilities: DataSourceCapabilities): void {
-    CAPABILITIES_REGISTRY[capabilities.key] = capabilities;
-}