@rebasepro/types 0.17.3 → 0.18.1

package/dist/types/properties.d.ts

@@ -1,3 +1,4 @@
+import type { ResourceRef } from "./resources.js";
 import type { Entity, EntityReference, EntityRelation, EntityValues, GeoPoint, Vector } from "./entities.js";
 import type { Relation, ResolvedRelation } from "./relations.js";
 import type { ColorKey, ColorScheme } from "./chips.js";
@@ -77,6 +78,129 @@ export type MongoProperties = {
  * unknown but the narrowed property constraint must be satisfied.
  */
 export type EngineProperties = PostgresProperties | FirebaseProperties | MongoProperties;
+/**
+ * What a key the surrounding shape does not declare resolves to.
+ *
+ * Nothing is assignable to it — it has required members nobody can spell — so
+ * the key errors. It is a *named* type rather than `never` purely for the
+ * message: TypeScript prints the target, so the compiler reads back the key that
+ * is wrong and the keys that would have been right, instead of saying "not
+ * assignable to type 'never'".
+ *
+ * ```
+ * Type '{ required: true }' is not assignable to type
+ *   '{ readonly required: true } & NoSuchKey<"validaton", "name" | "type" | "validation" | …>'.
+ *   Property 'didYouMean' is missing …
+ * ```
+ *
+ * `Known` is the set of keys that *were* available. TypeScript elides a long
+ * union after a few members, so this is a hint and not an exhaustive listing —
+ * which is the right trade: the near-miss is usually alphabetically adjacent to
+ * the key that was meant, and a wall of 25 names would be read by nobody.
+ */
+export type NoSuchKey<K extends PropertyKey, Known extends PropertyKey = never> = {
+    /** The key that was written, so the compiler reads it back verbatim. */
+    readonly noSuchKey: K;
+    /** The keys that were available. Required, so the type is unsatisfiable. */
+    readonly didYouMean: Known;
+};
+/**
+ * What a property whose `type` the engine does not have resolves to.
+ *
+ * Same trick as {@link NoSuchKey}, for a different mistake: a `relation` on a
+ * Firestore collection, a `vector` on MongoDB.
+ *
+ * Without it, `ExactProperty<V, never>` is `V & {}` — which is `V`, and
+ * therefore no check at all. The gate is normally caught one level up, by the
+ * builder's `P extends FirebaseProperties` constraint; this is what catches it
+ * when `StrictProperties` is applied to a property map that carries no such
+ * constraint, and it reports on the property rather than on the whole map.
+ */
+export type PropertyTypeNotOnThisEngine<T> = {
+    /** The `type` tag that has no home on this engine. Required, so nothing fits. */
+    readonly __rebasePropertyTypeNotOnThisEngine: T;
+};
+/**
+ * A relation checked against the concrete member of the union its own `kind`
+ * selects, rather than against the union as a whole.
+ *
+ * `Relation` is closed — `BelongsToRelation` has `localKey` and no
+ * `foreignKeyOnTarget`, `HasManyRelation` the reverse — but excess-property
+ * checking against a *union* passes any key that any member declares. So
+ * `{ kind: "belongsTo", foreignKeyOnTarget: "author_id" }` typechecked, and
+ * described a link that cannot exist: the generator reads `localKey`, defaults
+ * it to `<relationName>_id`, and the column the author actually named is never
+ * looked at. The relation resolves to a different link than the one written.
+ *
+ * The runtime already refuses this — `validate-config` rejects a link field that
+ * does not belong to the kind — so this is the same rule one stage earlier,
+ * where it costs a red squiggle instead of a failed boot.
+ */
+type StrictRelation<R> = R extends {
+    kind: infer K;
+} ? R & {
+    [Key in Exclude<keyof R, keyof Extract<Relation, {
+        kind: K;
+    }>>]: NoSuchKey<Key, keyof Extract<Relation, {
+        kind: K;
+    }>>;
+} : R;
+/**
+ * `V`, plus every key it carries that `Shape` does not declare, typed so it
+ * cannot be satisfied.
+ *
+ * The `relation` block is descended into, because it is the one nested shape
+ * that is a closed union rather than a single interface — see
+ * {@link StrictRelation}. The rest (`array.of`, `map.properties`, the `admin`
+ * options) are left to the weak-type check and the boot validator.
+ */
+type ExactProperty<V, Shape> = [Shape] extends [never] ? PropertyTypeNotOnThisEngine<V extends {
+    type: infer T;
+} ? T : never> : V & {
+    [K in Exclude<keyof V, keyof Shape>]: NoSuchKey<K, keyof Shape>;
+} & (V extends {
+    relation: infer R;
+} ? {
+    relation: StrictRelation<R>;
+} : unknown);
+/**
+ * A property map in which each value is checked against the *concrete* member of
+ * the property union that its own `type` tag selects.
+ *
+ * ### Why this type has to exist
+ *
+ * `defineCollection` takes `properties: P` where `const P extends Properties`.
+ * `Properties` is an index signature, and **every object literal is assignable
+ * to an index signature** — extra keys included — so TypeScript's
+ * excess-property check never ran inside a property. The consequences were not
+ * theoretical:
+ *
+ * - `validation` misspelled `validaton` compiled, and the field was quietly not
+ *   required.
+ * - `multiline: true` and `markdown: true` written flat — the shape the docs
+ *   themselves showed — compiled, and then the backend refused to boot with a
+ *   migration hint pointing at `admin: { … }`.
+ * - `multiSelect: true`, a key that exists nowhere in the codebase, compiled.
+ *
+ * Annotating `const c: PostgresCollectionConfig = { … }` *did* catch all three,
+ * which is the tell: the checking was never missing, only bypassed by the
+ * inference the builder exists to provide.
+ *
+ * The map is homomorphic (`[K in keyof P]`), so it stays invertible and `const P`
+ * inference is unaffected — `admin.display.title` still completes over the
+ * collection's own keys. Verified against the full probe suite before landing.
+ *
+ * Nested shapes (`array.of`, `map.properties`, and the `admin` block's own
+ * options) are not reached by this type; the weak-type check covers an `admin`
+ * block whose keys are *all* unknown, and the boot validator covers the rest.
+ */
+export type StrictProperties<P, AllowedProperty> = {
+    [K in keyof P]: P[K] extends {
+        type: infer T;
+    } ? ExactProperty<P[K], Extract<AllowedProperty, {
+        type: T;
+    }>> : P[K];
+};
 /**
  * A helper type to infer the underlying data type from a Property definition.
  * This is the core of the type inference system.
@@ -128,9 +252,20 @@ export type InferEntityType<P extends Properties> = {
 };
 export interface BaseProperty<CustomProps = unknown> {
     /**
-     * Property name (e.g. Product)
+     * The label the admin panel shows for this field — a column header, a form
+     * label, a card caption.
+     *
+     * Optional, and derived from the property key when absent
+     * (`publishDate` -> "Publish Date", via `prettifyIdentifier`, which is the
+     * same derivation the collection editor already uses when it suggests one).
+     *
+     * It was required, and that was a UI concern levied on everyone: a headless
+     * project has no panel and no reason to invent display names, yet could not
+     * declare a property without one. Set it when the derived label is wrong —
+     * `"URL"` rather than "Url", `"Postcode"` rather than "Zip" — which is the
+     * only time it earns the line.
      */
-    name: string;
+    name?: string;
     /**
      * Property description, always displayed under the field
      */
@@ -370,6 +505,15 @@ export interface VectorProperty extends BaseProperty {
      * Default value for new entities.
      */
     defaultValue?: Vector;
+    /**
+     * How many numbers each embedding has — 1536 for OpenAI's
+     * `text-embedding-3-small`, 768 for many sentence transformers.
+     *
+     * **Required, and effectively frozen.** It is the column's width
+     * (`vector(1536)`), so changing it is a rewrite of every row, and every
+     * stored embedding was produced by a model that no longer matches. Take the
+     * number from the model you are actually going to use.
+     */
     dimensions: number;
     /**
      * ANN index configuration for this column.
@@ -383,6 +527,11 @@ export interface VectorProperty extends BaseProperty {
      * embedding is left unindexed rather than failing the boot.
      */
     index?: VectorIndexConfig | false;
+    /**
+     * The rules every property has: `required`, `unique`. A vector has no
+     * length or range rules of its own — {@link dimensions} is the column's
+     * width, and the database enforces it.
+     */
     validation?: PropertyValidationSchema;
 }
 /**
@@ -394,6 +543,10 @@ export interface BinaryProperty extends BaseProperty {
      * Default value for new entities. Must be a base64-encoded string.
      */
     defaultValue?: string;
+    /**
+     * The rules every property has: `required`, `unique`. Size limits belong to
+     * the upload path, not here.
+     */
     validation?: PropertyValidationSchema;
 }
 export interface DateProperty extends BaseProperty {
@@ -530,6 +683,12 @@ export interface RelationProperty extends BaseProperty {
      *     relation: { kind: "manyToMany", target: () => tagsCollection }
      * }
      * ```
+     *
+     * Optional because there is a second way to say the same thing: an entry in
+     * the collection's `relations` array whose `relationName` is this
+     * property's key. One of the two is required, and boot refuses a
+     * `type: "relation"` property that has neither — a field with no link is a
+     * relation in name only.
      */
     relation?: Relation;
     /**
@@ -645,15 +804,29 @@ export interface MapProperty extends BaseProperty {
     keyValue?: boolean;
 }
 /**
+ * What a `dynamicProps` builder is handed when it computes a property.
+ *
+ * Called on every render of the form, for one field, so it is a pure function of
+ * these arguments: the entity being edited, the value in this field, and who is
+ * editing. It runs **in the browser** and shapes what is offered — it is not a
+ * security boundary, and a rule that must hold has to be a security rule as well.
+ *
  * @group Entity properties
  */
 export type PropertyBuilderProps<M extends Record<string, unknown> = Record<string, unknown>> = {
+    /** The entity's values as they stand right now, including unsaved edits. */
     values: Partial<M>;
+    /** The values as last saved, or `undefined` for an entity being created. */
     previousValues?: Partial<M>;
+    /** The value in *this* field. `undefined` before anything is typed. */
     propertyValue?: unknown;
+    /** Position within the parent array, when this property is an array element. */
     index?: number;
+    /** The collection path this entity belongs to. */
     path: string;
+    /** The entity's id, or `undefined` while it is being created. */
     entityId?: string | number;
+    /** Who is editing — the signed-in user and their roles. */
     authController: AuthState;
 };
 /**
@@ -723,12 +896,19 @@ export interface PropertyValidationSchema {
  * @group Entity properties
  */
 export interface NumberPropertyValidationSchema extends PropertyValidationSchema {
+    /** Smallest accepted value, **inclusive**. `min: 0` accepts `0`. */
     min?: number;
+    /** Largest accepted value, **inclusive**. `max: 100` accepts `100`. */
     max?: number;
+    /** Must be strictly below this. The exclusive twin of {@link max}. */
     lessThan?: number;
+    /** Must be strictly above this. The exclusive twin of {@link min}. */
     moreThan?: number;
+    /** Must be greater than zero. `0` is rejected — use `min: 0` to allow it. */
     positive?: boolean;
+    /** Must be less than zero. `0` is rejected. */
     negative?: boolean;
+    /** No fractional part. Does not change the column type; see `columnType`. */
     integer?: boolean;
 }
 /**
@@ -736,16 +916,42 @@ export interface NumberPropertyValidationSchema extends PropertyValidationSchema
  * @group Entity properties
  */
 export interface StringPropertyValidationSchema extends PropertyValidationSchema {
+    /** Exactly this many characters — a country code, a fixed-width reference. */
     length?: number;
+    /** Fewest characters accepted, inclusive. */
     min?: number;
+    /**
+     * Most characters accepted, inclusive.
+     *
+     * Also sizes the column: a `max` turns `TEXT` into `VARCHAR(max)`, so
+     * lowering it on a table that already has longer rows is a migration the
+     * database will refuse, not just a stricter form.
+     */
     max?: number;
+    /**
+     * A pattern the whole value must match.
+     *
+     * A `string` is compiled per request, so it must be a valid regular
+     * expression — one that will not compile is rejected at boot, because
+     * `toPattern` answers `undefined` for it and the caller reads
+     * `if (pattern && !pattern.test(value))`: the rule would silently become no
+     * rule. A `RegExp` literal has already been compiled by the engine.
+     */
     matches?: string | RegExp;
     /**
      * Message displayed when the input does not satisfy the regex in `matches`
      */
     matchesMessage?: string;
+    /**
+     * Strip leading and trailing whitespace **before** saving.
+     *
+     * A transform, not a check: it changes the value that is written, which is
+     * what makes it the fix for "the same tag twice, one with a trailing space".
+     */
     trim?: boolean;
+    /** Lowercase the value before saving. A transform, like {@link trim}. */
     lowercase?: boolean;
+    /** Uppercase the value before saving. A transform, like {@link trim}. */
     uppercase?: boolean;
 }
 /**
@@ -753,7 +959,9 @@ export interface StringPropertyValidationSchema extends PropertyValidationSchema
  * @group Entity properties
  */
 export interface DatePropertyValidationSchema extends PropertyValidationSchema {
+    /** Earliest accepted date, inclusive. A fixed instant, not "today". */
     min?: Date;
+    /** Latest accepted date, inclusive. A fixed instant, not "today". */
     max?: Date;
 }
 /**
@@ -761,7 +969,9 @@ export interface DatePropertyValidationSchema extends PropertyValidationSchema {
  * @group Entity properties
  */
 export interface ArrayPropertyValidationSchema extends PropertyValidationSchema {
+    /** Fewest elements accepted, inclusive. Counts elements, not characters. */
     min?: number;
+    /** Most elements accepted, inclusive. Counts elements, not characters. */
     max?: number;
 }
 /**
@@ -775,8 +985,11 @@ export type StorageConfig = {
      * in `initializeRebaseBackend({ storage: { ... } })`.
      *
      * When omitted, the default storage source is used.
+     *
+     * A string key, or the handle `bucket("media")` returned — the handle is
+     * the same name spelled once, and `defineCollection` records its key.
      */
-    storageSource?: string;
+    storageSource?: ResourceRef;
     /**
      * Store files for this property as **public**: they are placed under the
      * public prefix and served via stable, token-less, permanent, CDN-cacheable

package/dist/types/relations.d.ts

@@ -34,13 +34,45 @@ export interface RelationBase {
     relationName?: string;
     /** The collection on the other end. */
     target: () => AnyCollectionConfig;
+    /**
+     * What the database does to this side's foreign key when the target row's
+     * key changes. Emitted as the constraint's `ON UPDATE`.
+     *
+     * Unset means no clause, which Postgres reads as `NO ACTION`. Set
+     * `"cascade"` when the target's key is a natural key that can be edited —
+     * a slug, a SKU — so the pointers follow it.
+     *
+     * Only a `belongsTo` puts the key on this table, so this is the only kind
+     * where the clause is written here; on the other kinds it describes the
+     * constraint the target's own column carries.
+     */
     onUpdate?: OnAction;
+    /**
+     * What the database does to this side's rows when the target row is
+     * deleted. Emitted as the constraint's `ON DELETE`.
+     *
+     * Defaults, when unset, to `"set null"` for an optional relation and
+     * **`"restrict"`** for a required one. `NOT NULL` says a child cannot exist
+     * without a parent; it does not say deleting the parent should delete the
+     * child. Ask for `"cascade"` when that is what you mean — it is the one
+     * value that destroys rows you did not name.
+     *
+     * A `manyToMany` is the exception: its junction rows default to
+     * `"cascade"`, because the row deleted there is the link and not the target.
+     */
     onDelete?: OnAction;
-    /** Presentation overrides applied when this relation is rendered as a tab. */
+    /**
+     * Presentation overrides applied when this relation is rendered as a tab.
+     *
+     * Whether the link is *required* is not here: it is
+     * `validation: { required: true }` on the declaring property, the same key
+     * every other field uses. A relation carried its own copy until 0.18, and
+     * the two disagreed by construction — the DDL generator read the property
+     * (so the column was `NOT NULL`) while codegen read the relation (so the
+     * generated `Insert` type made it optional), and a `create()` that
+     * typechecked failed at the database.
+     */
     overrides?: Partial<AnyCollectionConfig>;
-    validation?: {
-        required?: boolean;
-    };
 }
 /**
  * This collection holds the foreign key. One target row per source row.
@@ -179,6 +211,14 @@ 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";
+    /**
+     * The joins, in order, from this collection's table to the target's.
+     *
+     * Each step names a table and the columns to join it on; the last step's
+     * table is the target. Read-only, because Rebase will not work out how to
+     * write through an arbitrary chain, and guessing is what this kind exists to
+     * stop.
+     */
     joinPath: JoinStep[];
 }
 /**
@@ -212,15 +252,27 @@ export type ResolvedRelation = ResolvedBelongsTo | ResolvedHasOne | ResolvedHasM
 export interface ResolvedRelationBase {
     /** Always set: defaulted during resolution if the author omitted it. */
     relationName: string;
+    /**
+     * The collection on the other end.
+     *
+     * Still a thunk — a relation between two collections that import each other
+     * has to be — but normalised: resolution unwraps the module namespace the
+     * author's `() => import(…)` may hand back, so every consumer gets the
+     * config and not a `{ default: … }` wrapper.
+     */
     target: () => AnyCollectionConfig;
     /** The target's slug, resolved once so consumers need not call `target()`. */
     targetSlug: string;
+    /** As authored — see {@link RelationBase.onUpdate}. Defaults are not filled in. */
     onUpdate?: OnAction;
+    /**
+     * As authored — see {@link RelationBase.onDelete}. `undefined` here means
+     * the author said nothing, and the DDL generator picks the default; it does
+     * **not** mean "no action".
+     */
     onDelete?: OnAction;
+    /** Presentation overrides applied when this relation is rendered as a tab. */
     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
@@ -290,6 +342,11 @@ export interface ResolvedManyToMany extends ResolvedRelationBase {
     cardinality: "many";
     writable: true;
     shared: true;
+    /**
+     * The junction table and its two key columns, with every default filled in:
+     * the table from both table names sorted and joined, the columns from each
+     * endpoint's slug.
+     */
     through: {
         table: string;
         sourceColumn: string;
@@ -300,6 +357,7 @@ export interface ResolvedManyToMany extends ResolvedRelationBase {
 export interface ResolvedVia extends ResolvedRelationBase {
     kind: "via";
     writable: false;
+    /** The chain as authored — see {@link ViaRelation.joinPath}. Nothing to default. */
     joinPath: JoinStep[];
 }
 /** Relations whose target row carries this collection's key. @group Models */

package/dist/types/resource_kinds.d.ts

@@ -11,7 +11,9 @@
  * that ships an engine this package has never heard of says so at the call site
  * instead of looking like a typo of one that exists.
  */
-import { type DeclareOptions, type ResourceHandle, type ResourceTransport } from "./resources.js";
+import { type DeclareOptions, type ResourceDeclaration, type ResourceHandle } from "./resources.js";
+import { type DataSourceDefinition } from "./data_source.js";
+import { type StorageSourceDefinition } from "./storage_source.js";
 /** Options a database accepts beyond the common ones. */
 export interface DatabaseOptions extends DeclareOptions {
     /**
@@ -94,6 +96,20 @@ export interface BucketOptions extends DeclareOptions {
     publicRead?: boolean;
     /** Key prefix within the bucket, for sharing one bucket between sources. */
     prefix?: string;
+    /**
+     * Serve unqualified uploads — a storage property with no `storageSource` —
+     * from this bucket.
+     *
+     * A project that declares only `bucket("media")` has no default bucket, and
+     * the registry used to promote the one it found with a warning. That is a
+     * decision about where a user's files land, made by the framework, on the
+     * strength of declaration order; it also produced two different
+     * destinations either side of a deploy, because the synthesized local
+     * default is dropped in production and the promotion is not. So it is now
+     * a boot error, and this is one of the two ways to answer it — the other
+     * being `bucket()`, which declares the default bucket itself.
+     */
+    default?: boolean;
     /**
      * The credential set this bucket signs with, when several share one.
      *
@@ -116,12 +132,20 @@ export type BucketHandle = ResourceHandle;
  * Declare a bucket.
  *
  * ```ts
- * export const media = bucket("media", { transport: "direct" });
+ * export const uploads = bucket({ engine: "s3" });               // the default one
+ * export const media   = bucket("media", { transport: "direct" });
  * ```
  *
  * `transport: "direct"` means a provider SDK talks to the bucket and the
  * backend is not in the upload path.
+ *
+ * The options-only form exists for the same reason `database`'s does: the
+ * default bucket has no name to pass, and without it the only way to configure
+ * one was `bucket("(default)", { … })` — writing out an internal sentinel to
+ * reach the options. Passing options where a key belongs used to throw "a
+ * bucket needs a non-empty key", which names neither the mistake nor the fix.
  */
+export declare function bucket(options?: BucketOptions): BucketHandle;
 export declare function bucket(key?: string, options?: BucketOptions): BucketHandle;
 /**
  * How hard the runtime tries to deliver.
@@ -203,10 +227,152 @@ export interface TopicHandle<T> extends ResourceHandle {
  * ```
  */
 export declare function topic<T = unknown>(key: string, options?: TopicOptions): TopicHandle<T>;
+/** What a cron declaration records, beyond its handler. */
+export interface CronResourceOptions extends DeclareOptions {
+    /** Five-field cron expression, e.g. `0 3 * * *`. */
+    schedule: string;
+    /**
+     * IANA zone the schedule is read in, e.g. `Europe/Madrid`.
+     *
+     * Without it the schedule is read in the process's own zone, which is
+     * whatever the host happens to be set to — UTC in nearly every container,
+     * the developer's own on a laptop. "3 AM" then means two different hours
+     * either side of a deploy. Naming the zone makes the declaration mean one
+     * thing everywhere.
+     */
+    timezone?: string;
+    description?: string;
+    enabled?: boolean;
+    timeoutSeconds?: number;
+    catchUpWindowSeconds?: number;
+}
+/**
+ * Declare a cron, as the scheduler's `defineCron` does on its way through.
+ *
+ * Projects do not call this: `defineCron` in `@rebasepro/server` does, so a
+ * cron file is both the handler and the declaration — one file, one name, and
+ * the graph derived from it says what a host needs to know without evaluating
+ * the handler. Exported so the derive step and the scheduler spell the
+ * declaration identically.
+ */
+export declare function declareCron(name: string, options: CronResourceOptions): ResourceHandle;
+/**
+ * What a function declaration records.
+ *
+ * Recorded by the derive step from the bundler's static analysis rather than
+ * by evaluating the function module: a function's handler is a Hono app that
+ * only needs to exist at request time, and evaluating it at build time would
+ * run its module-scope code in a process with none of its environment.
+ */
+export interface FunctionResourceOptions extends DeclareOptions {
+    /** Path inside the project, so a host can point at the file. */
+    file?: string;
+    /** `false` when the source imports a Node built-in or a package that needs one. */
+    portable?: boolean;
+    /** Why it is not portable — one short phrase per reason. */
+    requires?: string[];
+}
+/** Declare a function. Called by the derive step, not by projects. */
+export declare function declareFunction(name: string, options?: FunctionResourceOptions): ResourceHandle;
+/** Options a queue accepts beyond the common ones. */
+export interface QueueOptions extends DeclareOptions {
+    /** Attempts before a job is left failed. Default 5. */
+    maxAttempts?: number;
+}
+/** What a queue's handler receives. `attempt` counts from 1. */
+export type QueueHandler<T> = (payload: T, context: {
+    attempt: number;
+    queue: string;
+    jobId: string;
+}) => Promise<void> | void;
+/** Per-job options at enqueue time. */
+export interface QueueEnqueueOptions {
+    /** Earliest time the job may run. Defaults to now. */
+    runAt?: Date;
+    /** Attempts for this job, overriding the queue's. */
+    maxAttempts?: number;
+}
+/**
+ * What a queue enqueues through.
+ *
+ * Installed by `@rebasepro/server` at boot, alongside the topic runtime.
+ * Absent — config evaluated by the CLI, a unit test — enqueueing throws with
+ * the cause named, rather than resolving and dropping the job.
+ */
+export interface QueueRuntime {
+    enqueue(queue: string, payload: unknown, options?: QueueEnqueueOptions): Promise<{
+        id: string;
+    }>;
+}
+/** Install the transport queues enqueue through. Called by the server at boot. */
+export declare function setQueueRuntime(runtime: QueueRuntime | null): void;
+/** A queue's handler, as recorded for the worker to wire. */
+export interface QueueConsumer<T = unknown> {
+    queue: string;
+    handler: QueueHandler<T>;
+}
+/** Every declared queue handler, for the worker to wire. */
+export declare function declaredQueueConsumers(): QueueConsumer[];
+/** Forget declared queue handlers. For tests, alongside `resetDeclaredResources`. */
+export declare function resetDeclaredQueueConsumers(): void;
+/** A queue handle, carrying its payload type. */
+export interface QueueHandle<T> extends ResourceHandle {
+    /**
+     * Put a job on the queue.
+     *
+     * Resolves once the job is durably recorded, not once it has run. A row
+     * insert, so enqueued inside a transaction that rolls back it was never
+     * enqueued.
+     */
+    enqueue(payload: T, options?: QueueEnqueueOptions): Promise<{
+        id: string;
+    }>;
+    /**
+     * Declare the handler.
+     *
+     * One per queue: a queue is a work list with one consumer, which is what
+     * separates it from a topic. Work that several things must react to is a
+     * topic with several subscriptions.
+     */
+    handler(fn: QueueHandler<T>): void;
+}
+/**
+ * Declare a queue.
+ *
+ * ```ts
+ * export const thumbnails = queue<{ key: string }>("thumbnails");
+ * thumbnails.handler(async ({ key }) => { … });
+ * await thumbnails.enqueue({ key }, { runAt: new Date(Date.now() + 60_000) });
+ * ```
+ *
+ * The difference from a topic is the number of consumers: a queue has one, a
+ * topic fans out to every subscription. Both ride on the durable job queue, so
+ * declaring either turns it on.
+ */
+export declare function queue<T = unknown>(key: string, options?: QueueOptions): QueueHandle<T>;
+/**
+ * One declaration, as the data layer's definition.
+ *
+ * There is exactly one of these per kind, and everything that needs a
+ * definition goes through it — the frontend, the managed runtime's boot path,
+ * and an ejected project's own entrypoint. That is not tidiness: the mapping
+ * used to exist twice, once here and once in `@rebasepro/server`'s
+ * `graphToStorageSources`, and the two disagreed. The server's copy carried a
+ * bucket's `account`; this one dropped it, so a bucket declared with shared
+ * credentials resolved them on the managed runtime and resolved *nothing* in an
+ * ejected backend — the source was skipped and every upload to it answered 501.
+ *
+ * A field-by-field map is one line away from that failure at all times, so
+ * there is now one line to keep right instead of two to keep equal.
+ */
+export declare function resourceToDataSource(declaration: ResourceDeclaration): DataSourceDefinition;
+/** One declaration, as the storage layer's definition. See {@link resourceToDataSource}. */
+export declare function resourceToStorageSource(declaration: ResourceDeclaration): StorageSourceDefinition;
 /**
- * The declared databases, in the shape `<Rebase dataSources>` takes.
+ * The declared databases, as definitions.
  *
- * The frontend needs to know which sources exist and how they are reached — a
+ * Both the frontend and a project's own backend entrypoint read this. The
+ * frontend needs to know which sources exist and how they are reached — a
  * `direct`-transport source is one the browser talks to itself — and it imports
  * the same config package the backend does. Without these it would mean writing
  * the list a second time, by hand, next to the declarations, which is precisely
@@ -223,16 +389,6 @@ export declare function topic<T = unknown>(key: string, options?: TopicOptions):
  * would leave this empty — hence the side-effect import above rather than a
  * bare re-export.
  */
-export declare function declaredDataSources(): {
-    key: string;
-    engine: string;
-    transport: ResourceTransport;
-    label?: string;
-}[];
-/** The declared buckets, in the shape `<Rebase storageSources>` takes. */
-export declare function declaredStorageSources(): {
-    key: string;
-    engine: string;
-    transport: ResourceTransport;
-    label?: string;
-}[];
+export declare function declaredDataSources(): DataSourceDefinition[];
+/** The declared buckets, as definitions. */
+export declare function declaredStorageSources(): StorageSourceDefinition[];