@rebasepro/common 0.17.3 → 0.18.1

package/dist/util/builders.d.ts

@@ -1,10 +1,49 @@
-import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBCollectionConfig, MongoProperties, PostgresCollectionConfig, PostgresProperties, User } from "@rebasepro/types";
+import { FirebaseCollectionConfig, FirebaseProperties, FirebaseProperty, InferEntityType, MongoDBCollectionConfig, MongoProperties, MongoProperty, PostgresCollectionConfig, PostgresProperties, PostgresProperty, Properties, Property, StrictProperties, User, type ResourceRef } from "@rebasepro/types";
+/** The engines a collection can declare. `postgres` when it says nothing. */
+type CollectionEngine = "postgres" | "firestore" | "mongodb";
 /**
- * Define a PostgreSQL-backed collection with full type inference.
+ * The concrete collection type an `engine` selects.
+ *
+ * This builder used to be three overloads — one per engine — and overload
+ * resolution is what made its errors unreadable. When no overload matches,
+ * TypeScript emits **one** diagnostic at the call site listing each overload's
+ * *first* failure, so a misspelled key on a Postgres collection came back as
+ * three paragraphs of `No overload matches this call. Overload 1 of 3 … Overload
+ * 3 of 3, '(collection: Omit<MongoDBCollectionConfig<…>>)'` — pointing at
+ * `defineCollection(` and blaming a database the project does not use.
+ *
+ * One signature, with the engine as a type parameter, reports the error at the
+ * key instead. Same fix as `@rebasepro/cms-types`, and deliberately the same
+ * shape: this is the builder a headless (`--headless`) scaffold, `rebase schema
+ * introspect` output and the example app's own collections use, so the two must
+ * not diverge.
+ */
+type CollectionConfigForEngine<E, P, USER extends User> = E extends "firestore" ? FirebaseCollectionConfig<EntityShapeOf<P>, USER> : E extends "mongodb" ? MongoDBCollectionConfig<EntityShapeOf<P>, USER> : PostgresCollectionConfig<EntityShapeOf<P>, USER>;
+/**
+ * `InferEntityType`, tolerant of a property map that has an error in it.
+ *
+ * The key set has to survive a bad property, or one mistake hides every other
+ * check that reads it. See `KEYS` on the signature below.
+ */
+type EntityShapeOf<P> = InferEntityType<{
+    [K in keyof P]: P[K] extends Property ? P[K] : Property;
+}>;
+/** The property union an engine admits — the engine gate, as a type. */
+type PropertyForEngine<E> = E extends "firestore" ? FirebaseProperty : E extends "mongodb" ? MongoProperty : PostgresProperty;
+/** {@link PropertyForEngine} as a property map, for the `P` constraint. */
+type PropertiesForEngine<E> = E extends "firestore" ? FirebaseProperties : E extends "mongodb" ? MongoProperties : PostgresProperties;
+/**
+ * Define a collection with full type inference. Postgres unless `engine` says
+ * otherwise.
  *
  * The `const P` generic captures literal property types from your
- * `properties` object, which enables autocomplete on `display.title`,
- * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
+ * `properties` object, so every key that names a property — a security rule's
+ * `ownerField`, a relation's `localKey`, an entity callback's `value` — is
+ * checked against the collection's own property names rather than `string`.
+ *
+ * This is the builder for a project with no admin panel. One with an admin
+ * panel wants `defineCollection` from `@rebasepro/cms-types`, which is the same
+ * function with the `admin` block type-checked.
  *
  * @example
  * ```ts
@@ -16,33 +55,39 @@ import { FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBC
  *         name: { name: "Name", type: "string", validation: { required: true } },
  *         price: { name: "Price", type: "number" },
  *     },
- *     display: { title: "name" },  // ✅ autocomplete: "name" | "price"
- *     sort: ["price", "asc"], // ✅ autocomplete on first element
+ *     securityRules: [{ operation: "select", access: "public" }]
  * });
  * ```
  *
  * @group Builder
  */
-export declare function defineCollection<const P extends PostgresProperties, USER extends User = User>(collection: Omit<PostgresCollectionConfig<InferEntityType<P>, USER>, "properties"> & {
-    properties: P;
-}): PostgresCollectionConfig<InferEntityType<P>, USER> & {
-    properties: P;
-};
+export declare function defineCollection<const E extends CollectionEngine = "postgres", 
 /**
- * Define a Firestore-backed collection with full type inference.
- * @group Builder
+ * The properties, **constrained**. This is what checks them, and what
+ * supplies the contextual type inside them: without a constraint the
+ * parameter of an inline `callbacks: { beforeSave: ({ value }) => … }` has
+ * nothing to be typed from, and TypeScript reports an implicit `any` on a
+ * callback the author wrote correctly.
  */
-export declare function defineCollection<const P extends FirebaseProperties, USER extends User = User>(collection: Omit<FirebaseCollectionConfig<InferEntityType<P>, USER>, "properties"> & {
-    properties: P;
-}): FirebaseCollectionConfig<InferEntityType<P>, USER> & {
-    properties: P;
-};
+const P extends PropertiesForEngine<E> & Properties = PropertiesForEngine<E> & Properties, 
 /**
- * Define a MongoDB-backed collection with full type inference.
- * @group Builder
+ * The properties again, **unconstrained**, and this is why there are two.
+ *
+ * A constraint TypeScript cannot satisfy is one it silently falls back
+ * from: one property with a bad `defaultValue` made `P` become
+ * `PostgresProperties`, the entity shape become `Record<string, unknown>`,
+ * and every key that is checked against the property names — `display.title`,
+ * `propertiesOrder`, `sort` — widen to `string` and stop being checked.
+ *
+ * `KEYS` has no constraint to fall back from, so `keyof KEYS` survives a bad
+ * property and the rest of the collection is still checked against the real
+ * key set.
  */
-export declare function defineCollection<const P extends MongoProperties, USER extends User = User>(collection: Omit<MongoDBCollectionConfig<InferEntityType<P>, USER>, "properties"> & {
-    properties: P;
-}): MongoDBCollectionConfig<InferEntityType<P>, USER> & {
-    properties: P;
+const KEYS = Properties, USER extends User = User>(collection: Omit<CollectionConfigForEngine<E, KEYS, USER>, "properties" | "engine" | "dataSource"> & {
+    engine?: E;
+    properties: StrictProperties<P, PropertyForEngine<E>> & KEYS;
+    dataSource?: ResourceRef;
+}): CollectionConfigForEngine<E, KEYS, USER> & {
+    properties: KEYS;
 };
+export {};

package/dist/util/callback-errors.d.ts

@@ -0,0 +1,77 @@
+import { RebaseApiError } from "@rebasepro/types";
+/**
+ * The code a write carries when a collection callback rejected it and did not
+ * say how. Distinct from `INVALID_INPUT`, which the framework's own validation
+ * raises: this one means *your* rule refused, so the message is the author's.
+ *
+ * `details.stage` names which callback refused — `beforeSave`, `beforeDelete`,
+ * `afterSave` or `afterDelete`. An `after*` hook runs inside the write's
+ * transaction, so a throw there rolls the row back too; the caller is told the
+ * write did not happen and which hook decided that.
+ */
+export declare const CALLBACK_REJECTED = "CALLBACK_REJECTED";
+/**
+ * Turn whatever a user callback threw into something the API layer can answer
+ * with.
+ *
+ * ### Why a plain `throw` has to mean 400
+ *
+ * Both `docs/collections/callbacks.md` ("Throw an error to **block the save**")
+ * and `docs/backend/hooks.md` ("the operation is rejected with an HTTP 400
+ * error response") promised this, and neither delivered it: an `Error` thrown
+ * from `beforeSave` reached the client as
+ *
+ *     500 {"error":{"message":"Internal Server Error","code":"INTERNAL_ERROR"}}
+ *
+ * with the author's message visible only in the server log, because the error
+ * normalizer masks 5xx bodies — correctly, since a 500 is by definition
+ * something the caller must not be told about.
+ *
+ * But a callback is not the server failing. It is the application speaking, in
+ * code its author wrote, about a request its author judged invalid. The
+ * conservative reading — "an unrecognised throw might be a real bug, so 500" —
+ * costs every validation rule its message and makes the documented example
+ * wrong. A rule that wants a 500 can still raise one explicitly.
+ *
+ * ### Why `after*` comes through here too
+ *
+ * `afterSave` and `afterDelete` run inside the write's transaction and are
+ * awaited, so a throw in one aborts the transaction: the row is not there when
+ * the request ends. Left unconverted, the caller saw a 500 for a write that a
+ * rule deliberately undid, and had no way to tell that from a database outage.
+ * Converted, it is the same 400 `CALLBACK_REJECTED` a `before*` hook produces,
+ * with `stage` naming the hook that refused.
+ *
+ * ### What passes through untouched
+ *
+ * Anything that already carries a status: `RebaseApiError` from
+ * `@rebasepro/types` (the browser-safe class a `config/collections/*.ts` file
+ * can import — the collection file is bundled into the admin SPA, so it may not
+ * import the server package), and the server's own `ApiError`, recognised
+ * structurally rather than by `instanceof` because a monorepo can resolve two
+ * copies of a package and `instanceof` is false across them.
+ *
+ * @param error What the callback threw.
+ * @param stage The callback name, for the log line.
+ * @param path  The collection path, for the log line.
+ */
+export declare function toCallbackError(error: unknown, stage: string, path: string): unknown;
+/**
+ * The refusal a callback expresses by returning `false` rather than throwing.
+ *
+ * `beforeDelete` is typed `boolean | void` and documented as "return false or
+ * throw to block deletion". Returning `false` did stop the delete — and then the
+ * route answered `204 No Content`, which says the row is gone. The admin panel
+ * removed it from the list, a client that trusted the status dropped it from its
+ * cache, and the next reload brought it back. A veto that reports success is
+ * worse than no veto.
+ *
+ * 403, not the 400 a throw produces: a throw carries the author's message and
+ * reads as "this input is wrong", while `false` is a flat refusal with no
+ * explanation — the server understood the request and will not perform it. The
+ * code is the same either way, so a client can handle both in one branch.
+ *
+ * @param stage The callback name, for `details.stage`.
+ * @param path  The collection path, for `details.path`.
+ */
+export declare function callbackRefusal(stage: string, path: string): RebaseApiError;

package/dist/util/callback-errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/util/index.d.ts

@@ -11,6 +11,7 @@ export * from "./permissions.js";
 export * from "./builders.js";
 export * from "./storage.js";
 export * from "./callbacks.js";
+export * from "./callback-errors.js";
 export * from "./relations.js";
 export * from "./resolve-relation.js";
 export * from "./auth-default-policies.js";

package/dist/util/policy/evaluatePolicy.d.ts

@@ -24,6 +24,12 @@ export interface PolicyEvalContext {
     uid?: string | null;
     /** The current user's application roles. */
     roles?: string[];
+    /**
+     * Whether this session is a GUEST — anonymous sign-in rather than an
+     * account. Optional, and absent means "not a guest", so a caller that does
+     * not know keeps the behaviour it had.
+     */
+    isAnonymous?: boolean;
     /** The row being evaluated, or null when no specific row is available. */
     entity: Entity | null;
 }

package/dist/util/relations.d.ts

@@ -27,6 +27,34 @@ export declare function isJunctionBackedRelation(relation: ResolvedRelation): bo
  * which is worth hearing about.
  */
 export declare function resolveCollectionRelations(collection: CollectionConfig): Record<string, ResolvedRelation>;
+/**
+ * The `type: "relation"` property that declares a link, or `undefined` for one
+ * that only exists in the collection's `relations` array.
+ *
+ * Both declaration sites end up in {@link resolveCollectionRelations}, and only
+ * one of them has a property to carry field-level facts — `name`, `admin`, and
+ * the one this exists for, `validation.required`.
+ */
+export declare function relationDeclaringProperty(collection: CollectionConfig, relation: ResolvedRelation): RelationProperty | undefined;
+/**
+ * Must every row of this collection point at a target through this link?
+ *
+ * Read from the declaring property's `validation.required` — the same key every
+ * other field uses, and the only place it lives.
+ *
+ * `RelationBase` carried its own `validation.required` until 0.18, which made
+ * this two questions rather than one. They were answered by different readers:
+ * the Postgres DDL generator asked the property (so the foreign-key column was
+ * `NOT NULL`) and the SDK type generator asked the relation (so the generated
+ * `Insert` type made the field optional). A `create()` that left the relation
+ * out therefore typechecked and then failed at the database with a not-null
+ * violation, and the two `required`s had to be written twice, identically, for
+ * the pair to agree.
+ *
+ * A relation with no declaring property — an entry in `relations` nothing
+ * points at — is not required. There is no field to fill in.
+ */
+export declare function isRelationRequired(collection: CollectionConfig, relation: ResolvedRelation): boolean;
 /**
  * The path of the collection a relation property points at, derived from the
  * property alone.
@@ -44,6 +72,19 @@ export declare function resolveCollectionRelations(collection: CollectionConfig)
  * is indistinguishable from a value of the wrong type.
  */
 export declare function getRelationTargetPath(property: RelationProperty): string | undefined;
+/**
+ * The table a collection reads and writes.
+ *
+ * `table` when it is set, otherwise `toSnakeCase(slug)` — which is what made it
+ * safe to drop `table` from the required fields on the config type: the runtime
+ * had always derived it, and the type was demanding a value it did not need.
+ *
+ * The `||` chain is load-bearing. `toSnakeCase(undefined)` returns `""`, not
+ * `undefined`, so the previous `??` chain short-circuited on the empty string
+ * and the name fallback could never run — a safety net that read like one and
+ * caught nothing. It was unreachable while `slug` was required; it stops being
+ * unreachable the moment anything constructs a config without one.
+ */
 export declare function getTableName(collection: CollectionConfig): string;
 /**
  * The variable name a generated table is bound to.

package/dist/util/table-name.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,47 +1,51 @@
 {
   "name": "@rebasepro/common",
-  "type": "module",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "description": "Rebase shared core — collection registry, data driver adapter and fluent query builder. No React dependency.",
-  "funding": {
-    "url": "https://github.com/sponsors/rebaseco"
+  "keywords": [
+    "rebase",
+    "cms",
+    "admin",
+    "typescript",
+    "headless",
+    "headless cms",
+    "content manager"
+  ],
+  "homepage": "https://rebase.pro",
+  "bugs": {
+    "url": "https://github.com/rebasepro/rebase/issues"
   },
-  "author": "Rebase",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/rebasepro/rebase.git",
     "directory": "packages/common"
   },
+  "funding": {
+    "url": "https://github.com/sponsors/rebasepro"
+  },
+  "license": "MIT",
+  "author": "Rebase",
+  "type": "module",
   "main": "./dist/index.es.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
-  "source": "src/index.ts",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.22.0"
   },
-  "keywords": [
-    "rebase",
-    "cms",
-    "admin",
-    "typescript",
-    "headless",
-    "headless cms",
-    "content manager"
-  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "development": "./dist/index.es.js",
-      "import": "./dist/index.es.js"
+      "import": "./dist/index.es.js",
+      "default": "./dist/index.es.js"
     },
     "./package.json": "./package.json"
   },
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.17.3",
-    "@rebasepro/utils": "0.17.3"
+    "@rebasepro/types": "0.18.1",
+    "@rebasepro/utils": "0.18.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -61,8 +65,7 @@
     "vite": "^8.1.5"
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "gitHead": "d935eefa5aa8d1009a2398cfac2c1e4ee9aeb6b6",
   "publishConfig": {
@@ -101,6 +104,7 @@
     "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../tooling/scripts/add-dts-extensions.mjs dist && node ../../tooling/scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
     "generateIcons": "ts-node --esm src/icons/generateIcons.ts"
   }