@rebasepro/types 0.19.1 → 0.19.2-canary.g09316f6

package/dist/types/collections.d.ts

@@ -6,6 +6,7 @@ import type { Relation } from "./relations.js";
 import type { SecurityRule } from "./security_rules.js";
 import type { SearchConfig } from "./search.js";
 import type { CollectionIndex } from "./indexes.js";
+import type { CollectionTenantConfig } from "./tenancy.js";
 /**
  * Base interface containing all driver-agnostic collection properties.
  * Use {@link PostgresCollectionConfig} or {@link FirebaseCollectionConfig} for
@@ -149,6 +150,12 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
     /**
      * User id of the owner of this collection. This is used only by plugins, or if you
      * are writing custom code
+     *
+     * **Admin form only — not enforced by the API or the database.** The
+     * collection editor stamps it on a collection it creates and shows it
+     * beside the name; nothing on the request path consults it. It is not an
+     * ownership check, and a collection with somebody else's id here is served
+     * to exactly the same callers as one with none.
      */
     ownerId?: string;
     /**
@@ -290,6 +297,58 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
      * rather than silently ignored.
      */
     indexes?: readonly CollectionIndex<Extract<keyof M, string>>[];
+    /**
+     * Turn `delete` into "stamp a timestamp", and hide stamped rows from reads.
+     *
+     * With this on, a delete — single, bulk or through a nested path — sets the
+     * field to `now()` instead of issuing a `DELETE`, and every read filters
+     * `<field> IS NULL` by default: `find`, `findById`, `count`, aggregates, the
+     * realtime refetch, and the loading of this collection through a relation.
+     * A restore is an ordinary update setting the field back to `null`. A real
+     * `DELETE` is still available as `delete(…, { hard: true })` / `?hard=true`,
+     * and needs exactly the same permission an ordinary delete does — it is the
+     * same operation, and gating it separately would be a second access-control
+     * surface for one verb.
+     *
+     * `true` uses `deletedAt` (column `deleted_at`). The object form renames the
+     * field. **Either way the collection must declare that property itself**, as
+     * a `date` — this flag says what a column *means*, it does not conjure the
+     * column into existence. A config that turns it on without the property is
+     * refused at boot rather than at the first delete, because the failure would
+     * otherwise land on a caller trying to remove a row.
+     *
+     * The hooks do not change: `beforeDelete` can still veto and `afterDelete`
+     * still fires. From the application's point of view the row was deleted;
+     * how the table records that is this flag's business.
+     *
+     * Postgres-only, like {@link SearchConfig}.
+     */
+    softDelete?: boolean | {
+        /**
+         * The `date` property that records the deletion. Defaults to
+         * `deletedAt`.
+         */
+        field?: string;
+    };
+    /**
+     * Scope every row of this collection to a tenant.
+     *
+     * One declaration replaces the four hand-written pieces a tenant-scoped
+     * table used to need — the `NOT NULL` column, the RLS rule, the value
+     * stamped on insert, and the index — and keeps them in agreement, because
+     * they are all derived from this.
+     *
+     * ```ts
+     * tenant: { field: "orgId", from: { claim: "org_id" } }
+     * ```
+     *
+     * The property must already be declared: this says what a column *means*,
+     * it does not create one. Postgres-only, like {@link SearchConfig} — RLS is
+     * what enforces the boundary.
+     *
+     * @see CollectionTenantConfig
+     */
+    tenant?: CollectionTenantConfig<M>;
 }
 /**
  * A collection backed by Firebase / Firestore.

package/dist/types/filter-operators.d.ts

@@ -37,16 +37,36 @@
  * @module
  */
 /**
- * Canonical sort representation: `[fieldName, direction]`.
+ * Where NULLs sort relative to real values on one key.
+ *
+ * Absent means the convention Postgres itself applies and the driver writes
+ * out: `NULLS LAST` ascending, `NULLS FIRST` descending. That convention was
+ * hardcoded and unstateable — a "newest first" list put every row with no date
+ * at the very top, and the only way out was to add a `is-not-null` filter and
+ * lose those rows entirely.
+ *
+ * The keyset comparison honours whatever is chosen here, so a cursor over a
+ * nullable key stays correct under either placement.
+ *
+ * @group Models
+ */
+export type NullsPlacement = "first" | "last";
+/**
+ * Canonical sort representation: `[fieldName, direction]`, optionally with a
+ * {@link NullsPlacement}.
  *
  * Used in `FindParams.orderBy`, `collection.sort`, and `FilterPreset.sort`.
- * The colon-string form (`"field:direction"`) exists only at the HTTP wire
- * boundary, handled by `serializeOrderBy` / `deserializeOrderBy` in
- * `@rebasepro/common`.
+ * The colon-string form (`"field:direction"`, or `"field:direction:nulls"`)
+ * exists only at the HTTP wire boundary, handled by `serializeOrderBy` /
+ * `deserializeOrderBy` in `@rebasepro/common`.
+ *
+ * The third slot is optional so every `[field, direction]` written before it
+ * existed is still exactly this type, and every `const [field, direction] =`
+ * destructure still reads what it always read.
  *
  * @group Models
  */
-export type OrderByTuple<Key extends string = string> = [Key, "asc" | "desc"];
+export type OrderByTuple<Key extends string = string> = [Key, "asc" | "desc", NullsPlacement?];
 /**
  * One sort key, or several applied in order of significance.
  *
@@ -83,7 +103,7 @@ export type SortKey<Key extends string = string> = Key | RelationAggregateSort;
  *
  * @group Models
  */
-export type OrderBySortTuple<Key extends string = string> = [SortKey<Key>, "asc" | "desc"];
+export type OrderBySortTuple<Key extends string = string> = [SortKey<Key>, "asc" | "desc", NullsPlacement?];
 /**
  * The aggregate functions a relation sort can apply.
  *
@@ -307,6 +327,17 @@ export declare const REST_TO_CANONICAL: Readonly<Record<RestFilterOp, WhereFilte
  * Codecs normalize the value of these conditions to `null`.
  */
 export declare const NULL_OPS: ReadonlySet<WhereFilterOp>;
+/**
+ * Operators whose operand is a **list** of values rather than one value.
+ *
+ * On the wire that list is always parenthesised — `in.(draft,review)` — which
+ * is what lets the REST codec tell `?status=in.(a,b)` (the operator) from
+ * `?status=in.progress` (a value that happens to start with an operator's
+ * name). See `deserializeSingle` in `@rebasepro/common`.
+ *
+ * @group Models
+ */
+export declare const LIST_OPS: ReadonlySet<WhereFilterOp>;
 /**
  * Every canonical operator, in a stable order. Useful for engine capability
  * declarations ({@link DataSourceCapabilities.filterOperators}) and for

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from "./relations.js";
 export * from "./policy.js";
 export * from "./rls-functions.js";
 export * from "./security_rules.js";
+export * from "./tenancy.js";
 export * from "./entity_callbacks.js";
 export * from "./websockets.js";
 export * from "./backend.js";

package/dist/types/policy.d.ts

@@ -236,7 +236,7 @@ export interface RawPolicyExpression {
  * An operand referenced by a {@link ComparePolicyExpression}.
  * @group Models
  */
-export type PolicyOperand = FieldPolicyOperand | OuterFieldPolicyOperand | LiteralPolicyOperand | AuthUidPolicyOperand | AuthRolesPolicyOperand;
+export type PolicyOperand = FieldPolicyOperand | OuterFieldPolicyOperand | LiteralPolicyOperand | AuthUidPolicyOperand | AuthRolesPolicyOperand | AuthClaimPolicyOperand;
 /** A column value on the row being evaluated. @group Models */
 export interface FieldPolicyOperand {
     kind: "field";
@@ -271,6 +271,43 @@ export interface AuthUidPolicyOperand {
 export interface AuthRolesPolicyOperand {
     kind: "authRoles";
 }
+/**
+ * A named claim on the caller's session token — compiles to
+ * `NULLIF(rebase.jwt() ->> '<name>', '')`.
+ *
+ * The operand multi-tenancy is built on, and the reason it is an operand rather
+ * than a {@link RawPolicyExpression}: a claim arrives as **text**, and the
+ * column it is compared against usually is not. `org_id = rebase.jwt() ->>
+ * 'org_id'` on a `uuid` column is not a policy that denies — it is
+ * `CREATE POLICY` failing with "operator does not exist: uuid = text", and a
+ * table left with RLS enabled and no policy denies every row. Casting the
+ * *column* to text instead compiles, but takes the index off the one predicate
+ * that is ANDed into every read of the table.
+ *
+ * As an operand the compiler can see both sides: it casts the claim to the
+ * column's type, guarded so a malformed claim denies rather than raising
+ * `invalid input syntax` on every query, and the column keeps its index.
+ *
+ * An absent claim, and a claim set to the empty string, are both NULL — and a
+ * comparison against NULL is never true, so a caller carrying no claim sees no
+ * rows rather than all of them.
+ *
+ * Only *custom* claims are reachable. `uid`, `roles`, `aal` and `isAnonymous`
+ * are identity claims written after the custom ones when a token is minted,
+ * precisely so a claims hook cannot assert them; they have their own operands
+ * ({@link AuthUidPolicyOperand}, {@link AuthRolesPolicyOperand}) and naming one
+ * here is refused.
+ *
+ * Postgres-authoritative: the JavaScript evaluator reports *unknown* rather
+ * than reproducing Postgres's cast semantics (uuid case folding, numeric
+ * widening) a second time and getting them subtly wrong.
+ * @group Models
+ */
+export interface AuthClaimPolicyOperand {
+    kind: "authClaim";
+    /** The claim's name on the token, e.g. `"org_id"`. */
+    name: string;
+}
 /** @group Models */
 export declare const policy: {
     true: () => TruePolicyExpression;
@@ -294,4 +331,5 @@ export declare const policy: {
     literal: (value: string | number | boolean | null) => LiteralPolicyOperand;
     authUid: () => AuthUidPolicyOperand;
     authRoles: () => AuthRolesPolicyOperand;
+    authClaim: (name: string) => AuthClaimPolicyOperand;
 };

package/dist/types/properties.d.ts

@@ -250,6 +250,28 @@ export type InferEntityType<P extends Properties> = {
 } & {
     -readonly [K in OptionalPropertyKeys<P>]?: InferPropertyType<P[K]>;
 };
+/**
+ * Per-field read and write permission, by application role.
+ *
+ * An omitted list is not an empty one, and the difference is the whole type:
+ * *omitted* delegates to the row — everyone the collection's security rules let
+ * read (or write) the row gets the field; *`[]`* is nobody, through the API, at
+ * any privilege. `["editor"]` is everyone holding `editor`, plus `admin`.
+ *
+ * @see BaseProperty.access
+ */
+export interface FieldAccess {
+    /**
+     * Roles that may read the field. Omitted = everyone the collection's RLS
+     * lets read the row. `[]` = nobody through the API.
+     */
+    read?: readonly string[];
+    /**
+     * Roles that may write the field. Omitted = everyone the collection's RLS
+     * lets write the row. `[]` = nobody through the API.
+     */
+    write?: readonly string[];
+}
 export interface BaseProperty<CustomProps = unknown> {
     /**
      * The label the admin panel shows for this field — a column header, a form
@@ -311,13 +333,56 @@ export interface BaseProperty<CustomProps = unknown> {
      * This is a server-side guarantee, unlike `admin.hideFromCollection`, which
      * only stops the admin panel from *rendering* a field and leaves it in the
      * JSON payload.
+     *
+     * Sugar for `access: { read: [], write: [] }` — the two are one mechanism,
+     * not two, and declaring both on the same property is refused at boot. Write
+     * whichever reads better: the flag says "this is the server's column", the
+     * empty lists say the same thing in the vocabulary of {@link FieldAccess}.
      */
     excludeFromApi?: boolean;
+    /**
+     * Who may read and who may write this one field.
+     *
+     * Row access is the collection's `securityRules`; this is the field inside
+     * the row. A caller the row's policies let through still does not receive a
+     * field their roles cannot read — it is *absent* from the response rather
+     * than `null`, so a client cannot tell a withheld value from a stored one by
+     * its shape — and a write naming a field their roles cannot write is a 400
+     * (`FIELD_NOT_WRITABLE`), never a silently dropped key.
+     *
+     * Roles are Rebase application roles, the same ones `policy.rolesOverlap`
+     * compiles against and the same list `rebase.roles()` reads inside a policy:
+     * whatever the call context carries as `user.roles`. `admin` satisfies any
+     * non-empty list, mirroring the `rolesOverlap(['admin'])` arm every baseline
+     * policy carries — a field-level rule must not lock an administrator out of
+     * their own data, and `rebase.dataAsAdmin` holds that role.
+     *
+     * The enforcement point is the API boundary. In-process writes through
+     * `rebase.data` / `rebase.dataAsAdmin` and the framework's own auth paths do
+     * not pass through it — the same exemption `excludeFromApi` has always had,
+     * and the reason it is possible to store a password hash at all.
+     *
+     * @example
+     * ```ts
+     * salary: {
+     *     type: "number",
+     *     // Readable by HR and by admins; writable by nobody through the API.
+     *     access: { read: ["hr"], write: [] }
+     * }
+     * ```
+     */
+    access?: FieldAccess;
     /**
      * Use this to define dynamic properties that change based on certain conditions
      * or on the entity's values. For example, you can make a field read-only if
      * another field has a certain value.
      * This function receives the same props as a `PropertyBuilder` and should return a partial `Property` object.
+     *
+     * **Admin form only — not enforced by the API or the database.** The
+     * function is bundled into the panel and called while a form renders. A
+     * write that never goes through a form never goes through it, so a rule
+     * that must hold for every caller belongs in {@link validation}, which the
+     * server checks, or in a security rule, which the database enforces.
      */
     dynamicProps?: (props: PropertyBuilderProps) => Partial<Property>;
     /**
@@ -328,6 +393,11 @@ export interface BaseProperty<CustomProps = unknown> {
      * - Edited via the collection editor UI
      * - Evaluated at runtime like property builders
      *
+     * **Admin form only — not enforced by the API or the database.** Like
+     * {@link dynamicProps}, these are evaluated while a form renders and shape
+     * what the panel offers. `conditions.required` does not make a column
+     * `NOT NULL` and does not make a write fail.
+     *
      * @see PropertyConditions for available condition options
      * @see https://jsonlogic.com/ for JSON Logic syntax
      */
@@ -367,12 +437,21 @@ export interface StringProperty extends BaseProperty {
      *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
      * 'uuid' -> Drizzle `.defaultRandom()` (Postgres gen_random_uuid())
-     * 'cuid' -> Drizzle `.default(sql\`cuid()\`)`
-     * Or any other random string to act as a raw SQL default expression: e.g. `nanoid()`
+     * Or any other string to act as a raw SQL default expression, written either
+     * bare (`gen_random_uuid()::text`) or in template form
+     * (``isId: "sql`my_id()`"``) — the wrapper is markup and is stripped before
+     * the SQL is written. The function has to exist: nothing here creates it.
+     *
+     * `"cuid"` is **refused on Postgres**, at config load. It emitted
+     * `DEFAULT cuid()` against a function Rebase has never created — not by a
+     * generator, not at boot, not in a migration — so the column has never had a
+     * working default and the first insert relying on it failed with
+     * `function cuid() does not exist`. Use `"uuid"`, or supply your own SQL
+     * expression above and create the function in a migration.
      *
      * On the UI side, the field automatically gets disabled on new entities if a string strategy is provided.
      */
-    isId?: boolean | "manual" | "uuid" | "cuid" | string;
+    isId?: boolean | "manual" | "uuid" | string;
     /**
      * You can use the enum values providing a map of possible
      * exclusive values the property can take, mapped to the label that it is
@@ -382,6 +461,10 @@ export interface StringProperty extends BaseProperty {
      * colors). If you need to ensure the order of the elements, you can pass
      * a `Map` instead of a plain object.
      *
+     * On a SQL store this compiles to a Postgres enum type named
+     * `<table>_<column>`, so the ids are the type's labels. An empty list is
+     * refused at config load: `CREATE TYPE … AS ENUM ()` is not valid SQL, and
+     * the column would reference a type nothing creates.
      */
     enum?: EnumValues;
     /**
@@ -396,6 +479,11 @@ export interface StringProperty extends BaseProperty {
      * provider (e.g. the ID in your `users` table).
      * You can also use a property builder to specify the user path dynamically
      * based on other values of the entity.
+     *
+     * **Admin form only — not enforced by the API or the database.** The column
+     * is an ordinary string; there is no foreign key to the users table and
+     * nothing resolves or checks the id on the way in. To make the link real,
+     * declare a `relation` to the auth collection instead.
      */
     userSelect?: boolean;
     /**
@@ -411,6 +499,29 @@ export interface StringProperty extends BaseProperty {
      * renders it — as a link, an image, a video — is `admin.urlPreview`.
      */
     url?: boolean;
+    /**
+     * Stamp this column with the **uid of the acting user**, on creation only
+     * (`user_on_create`) or on every write including creation
+     * (`user_on_update`). The `created_by` / `updated_by` twin of
+     * {@link DateProperty.autoValue}, which has always done the same for
+     * timestamps.
+     *
+     * The value is taken from the call context, not from the request body: a
+     * caller cannot claim to be somebody else by sending the field, because the
+     * driver overwrites whatever arrived. That is the whole point — a column
+     * whose value the caller supplies is not an audit column.
+     *
+     * With no acting user (an anonymous request, a service token, a seed
+     * script) the column is set to `null`. If it is also
+     * `validation: { required: true }`, that is a 400 rather than a null: a
+     * collection that demands to know who wrote a row is a collection that
+     * cannot accept an anonymous write.
+     *
+     * There is no foreign key here. The uid is a string, the user store may be
+     * another database entirely, and a deleted user must not take their audit
+     * trail with them — declare a `relation` if you want the join.
+     */
+    autoValue?: "user_on_create" | "user_on_update";
 }
 export interface NumberProperty extends BaseProperty {
     type: "number";
@@ -423,6 +534,27 @@ export interface NumberProperty extends BaseProperty {
      * If not provided, integer fields (where validation.integer is true or isId is true) default to `integer`, others to `numeric`.
      */
     columnType?: "integer" | "real" | "double precision" | "numeric" | "bigint" | "serial" | "bigserial";
+    /**
+     * Total significant digits for a `numeric` column — `NUMERIC(precision, scale)`.
+     *
+     * Money is the case this exists for. Without it a price lands as an
+     * *unbounded* `NUMERIC`, which stores `19.999999999999998` as faithfully as
+     * `19.99` and cannot be tightened afterwards without rewriting the column,
+     * so the rounding rule ends up living in whichever caller last touched the
+     * value. `precision: 10, scale: 2` makes the database the one that decides.
+     *
+     * Read only when the column is `numeric` — either declared
+     * ({@link NumberProperty.columnType}) or arrived at by default, which is
+     * what a non-integer `number` gets. Ignored on `integer`, `real`,
+     * `double precision` and the serial types, which have no modifier.
+     *
+     * Changing it on a live column is an `ALTER COLUMN … TYPE`, so `db push`
+     * plans it and the boot-time ensure reports it rather than applying it —
+     * the same treatment every other type change gets.
+     */
+    precision?: number;
+    /** Digits after the decimal point. Requires {@link NumberProperty.precision}. */
+    scale?: number;
     /**
      * Rules for validating this property
      */
@@ -434,14 +566,27 @@ export interface NumberProperty extends BaseProperty {
      * UI behavior: Field value cannot be changed after creation.
      *
      * You can set this to `"manual"` for a user-defined ID, or specify a generation strategy:
-     * 'increment' -> PostgreSQL `GENERATED BY DEFAULT AS IDENTITY` or auto-incrementing integer.
-     * Or any other random string to act as a raw SQL default expression.
+     * 'increment' -> PostgreSQL `INTEGER GENERATED BY DEFAULT AS IDENTITY`.
+     * Or any other string to act as a raw SQL default expression, bare or in
+     * template form (``isId: "sql`nextval('s')`"``).
+     *
+     * {@link NumberProperty.columnType} is **not read** beside
+     * `isId: "increment"`: an increment key is always INTEGER, because every
+     * foreign key and junction column that points at a numeric primary key is
+     * INTEGER, and a wider key would be referenced by narrower columns. Config
+     * validation warns when the two are written together.
      */
     isId?: boolean | "manual" | "increment" | string;
     /**
      * You can use the enum values providing a map of possible
      * exclusive values the property can take, mapped to the label that it is
      * displayed in the dropdown.
+     *
+     * Unlike a string enum, this creates **no Postgres enum type**: the column
+     * stays NUMERIC or INTEGER, so the values are offered by the panel and are
+     * not enforced by the database. (One used to be created, referenced by
+     * nothing, and every `db push` planned a DROP for it.) An empty list is
+     * refused at config load.
      */
     enum?: EnumValues;
 }
@@ -567,10 +712,18 @@ export interface DateProperty extends BaseProperty {
      * Set the granularity of the field to a date or date + time.
      * Defaults to `date_time`.
      *
+     * **Admin form only — not enforced by the API or the database.** It picks
+     * the picker. The column is whatever {@link columnType} says, and the API
+     * accepts a full timestamp either way — narrowing the widget does not
+     * narrow the value.
      */
     mode?: "date" | "date_time";
     /**
      * Timezone string to evaluate the date in.
+     *
+     * **Admin form only — not enforced by the API or the database.** It is the
+     * zone the panel reads and writes the value in; what is stored is a
+     * `timestamptz`, which has no zone of its own.
      */
     timezone?: string;
     /**
@@ -875,7 +1028,11 @@ export interface PropertyValidationSchema {
      */
     required?: boolean;
     /**
-     * Customize the required message when the property is not set
+     * Customize the required message when the property is not set.
+     *
+     * **Admin form only — not enforced by the API or the database.** It is the
+     * sentence the panel shows under the field; an API rejection carries its
+     * own error code and message.
      */
     requiredMessage?: string;
     /**
@@ -888,6 +1045,11 @@ export interface PropertyValidationSchema {
      * once per entry in the parent `ArrayProperty`. It has no effect if this
      * property is not a child of an `ArrayProperty`. It works on direct
      * children of an `ArrayProperty` or first level children of `MapProperty`
+     *
+     * **Admin form only — not enforced by the API or the database.** Unlike
+     * {@link unique}, which compiles to a constraint, this one is checked as
+     * the form is filled in: the column holds a JSON array, and nothing in
+     * Postgres is looking inside it.
      */
     uniqueInArray?: boolean;
 }
@@ -947,11 +1109,24 @@ export interface StringPropertyValidationSchema extends PropertyValidationSchema
      *
      * 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".
+     *
+     * **Admin form only — not enforced by the API or the database.** The panel
+     * applies it on its way to the API; a value written any other way arrives
+     * as it was sent. A transform that must always happen is a `beforeSave`
+     * callback, which runs on the server for every write.
      */
     trim?: boolean;
-    /** Lowercase the value before saving. A transform, like {@link trim}. */
+    /**
+     * Lowercase the value before saving. A transform, like {@link trim}.
+     *
+     * **Admin form only — not enforced by the API or the database.**
+     */
     lowercase?: boolean;
-    /** Uppercase the value before saving. A transform, like {@link trim}. */
+    /**
+     * Uppercase the value before saving. A transform, like {@link trim}.
+     *
+     * **Admin form only — not enforced by the API or the database.**
+     */
     uppercase?: boolean;
 }
 /**
@@ -1008,6 +1183,10 @@ export type StorageConfig = {
      * Advanced image resizing and cropping configuration.
      * Applied before upload to optimize storage and bandwidth.
      * Only applies to image MIME types: image/jpeg, image/png, image/webp
+     *
+     * **Admin form only — not enforced by the API or the database.** The
+     * resizing happens in the browser, before the bytes are sent. An upload
+     * that does not go through the panel is stored at its original size.
      */
     imageResize?: ImageResize;
     /**
@@ -1028,6 +1207,9 @@ export type StorageConfig = {
      * - `{propertyKey}` - ID of this property
      * - `{path}` - Path of this entity
      *
+     * **Admin form only — not enforced by the API or the database.** The panel's
+     * uploader resolves it; `client.storage.upload()` names its own `key`.
+     *
      * @param context
      */
     fileName?: string | ((context: UploadedFileContext) => string | Promise<string>);
@@ -1043,6 +1225,12 @@ export type StorageConfig = {
      * - `{entityId}` - ID of the entity
      * - `{propertyKey}` - ID of this property
      * - `{path}` - Path of this entity
+     *
+     * **Admin form only — not enforced by the API or the database.** Required
+     * on the type because a file field in the panel has to put the object
+     * somewhere, but it is the panel's uploader that resolves it. Nothing on
+     * the server confines an upload to this prefix — that is what a storage
+     * authorization rule is for.
      */
     storagePath: string | ((context: UploadedFileContext) => string);
     /**
@@ -1072,17 +1260,26 @@ export type StorageConfig = {
     /**
      * Use this callback to process the file before uploading it to the storage.
      * If nothing is returned, the file is uploaded as it is.
+     *
+     * **Admin form only — not enforced by the API or the database.** It runs in
+     * the browser, on the file the reader picked.
+     *
      * @param file
      */
     processFile?: (file: File) => Promise<File> | undefined;
     /**
      * Postprocess the saved value (storage path or URL)
      * after it has been resolved.
+     *
+     * **Admin form only — not enforced by the API or the database.**
      */
     postProcess?: (pathOrUrl: string) => Promise<string>;
     /**
      * You can use this prop in order to provide a custom preview URL.
      * Useful when the file's path is different from the original field value
+     *
+     * **Admin form only — not enforced by the API or the database.** It changes
+     * what the panel renders, never what is stored.
      */
     previewUrl?: (fileName: string) => string;
 };

package/dist/types/relations.d.ts

@@ -1,8 +1,27 @@
 import type { AnyCollectionConfig } from "./collections.js";
+import type { Properties } from "./properties.js";
 /**
  * @group Models
  */
 export type OnAction = "cascade" | "restrict" | "no action" | "set null" | "set default";
+/**
+ * The key a junction row's own columns are carried under, in both directions.
+ *
+ * A read that includes a `manyToMany` relation serves each related row with its
+ * link's columns nested here — `{ id: 5, name: "ts", _pivot: { role: "owner" } }`
+ * — and a membership write may name the same key on an element to state what
+ * the link should hold. One constant because the two have to be the same word:
+ * a wire name that differs between the read and the write it round-trips
+ * through is a shape no client can echo back.
+ *
+ * Leading underscore, like `_matches`: it reads as metadata about the row
+ * rather than as one of its columns. A payload property may not be named
+ * `_pivot` either — `checkJunctionPayload` refuses it — so the key means one
+ * thing wherever it appears.
+ *
+ * @group Models
+ */
+export declare const JUNCTION_PIVOT_KEY = "_pivot";
 /**
  * What kind of link a relation is.
  *
@@ -183,6 +202,52 @@ export interface ManyToManyRelation extends RelationBase {
         sourceColumn?: string;
         /** Junction column holding the **target's** key. */
         targetColumn?: string;
+        /**
+         * Extra columns the junction row carries, declared exactly like a
+         * collection's properties.
+         *
+         * A membership is often not only a membership. "This user is in that
+         * organisation" is really "…as an `owner`, since March"; "this tag is
+         * on that post" is really "…in third place". Until this existed the
+         * junction was two key columns and nothing else, so the role and the
+         * position had to become a collection of their own — which is a
+         * different data model, a different set of policies and a different
+         * URL, for what is still one link.
+         *
+         * The properties are read by the same planner that reads a
+         * collection's, so a payload column gets the type, `NOT NULL`,
+         * `DEFAULT`, `UNIQUE` and enum type it would get on a table. What it
+         * does **not** get is `indexes` (declared per collection, and no
+         * collection declares a junction), `search`, `vector`, or anything a
+         * relation would put on it — a payload property may not be a
+         * `relation`, a `reference` or a `vector`, and config validation
+         * refuses one that is.
+         *
+         * On the wire the values travel under {@link JUNCTION_PIVOT_KEY}: a
+         * read serves `{ …target, _pivot: { role } }`, and a membership write
+         * accepts `{ id, _pivot: { role } }` beside the bare ids.
+         *
+         * ```ts
+         * members: {
+         *     kind: "manyToMany",
+         *     target: () => users,
+         *     through: {
+         *         table: "org_members",
+         *         properties: {
+         *             role: { type: "string", enum: ["owner", "admin", "member"],
+         *                     defaultValue: "member", validation: { required: true } },
+         *             joinedAt: { type: "date", autoValue: "on_create" }
+         *         }
+         *     }
+         * }
+         * ```
+         *
+         * Both sides of the same junction may declare it, and both must agree:
+         * `resolveJunctionSpecs` refuses two declarations of the same payload
+         * key that do not describe the same column, because only one of them
+         * could ever be created.
+         */
+        properties?: Properties;
     };
 }
 /**
@@ -351,6 +416,12 @@ export interface ResolvedManyToMany extends ResolvedRelationBase {
         table: string;
         sourceColumn: string;
         targetColumn: string;
+        /**
+         * The payload columns as authored, or `{}` when there are none —
+         * never `undefined`, so a consumer reads one shape.
+         * See {@link ManyToManyRelation.through}.
+         */
+        properties: Properties;
     };
 }
 /** @group Models */