@rebasepro/common 0.20.0 → 0.21.0

package/dist/table-classification.d.ts

@@ -10,19 +10,6 @@ export type TableCategory = "rebase-internal" | "junction" | "user";
 export declare const REBASE_INTERNAL_SCHEMAS: readonly string[];
 /** Table-name prefixes that mark a table as Rebase-internal regardless of schema. */
 export declare const REBASE_INTERNAL_PREFIXES: readonly string[];
-/**
- * Synchronously classify a table based on naming conventions.
- *
- * @param tableName  - The unqualified name of the table.
- * @param schemaName - The schema the table belongs to (e.g. `"public"`, `"rebase"`).
- * @returns `"rebase-internal"` when the table belongs to a reserved schema or
- *          carries a reserved prefix; `"user"` otherwise.
- *
- * @remarks
- * Junction-table detection requires an async database query and is therefore
- * **not** handled by this function. Use {@link detectJunctionTables} to obtain
- * the set of junction tables, then reclassify as needed.
- */
 export declare function classifyTable(tableName: string, schemaName: string): TableCategory;
 /**
  * Convenience predicate that checks whether a table is Rebase-internal.

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

@@ -75,3 +75,49 @@ export declare function toCallbackError(error: unknown, stage: string, path: str
  * @param path  The collection path, for `details.path`.
  */
 export declare function callbackRefusal(stage: string, path: string): RebaseApiError;
+/**
+ * The collection a callback tier is about to be handed — or a refusal.
+ *
+ * Every callback props type declares `collection: CollectionConfig`,
+ * non-optional, and the documented global-callback examples dereference it
+ * (`if (collection.slug === "audit_log") return;`). The driver resolves that
+ * value from the registry, which answers `undefined` for a path it does not
+ * know, so the tiers used to receive it through a cast that quietly dropped the
+ * `| undefined`. A global `beforeSave` reading `collection.slug` then threw a
+ * `TypeError` that `toCallbackError` reported as a 400 `CALLBACK_REJECTED` —
+ * the author's own rule blamed for a value the framework failed to supply.
+ *
+ * Skipping the tier instead is not available. `afterRead` is documented as the
+ * place for "security-critical redaction (PII masking, row filtering) — no read
+ * path bypasses it", and a tier that silently does not run on the paths the
+ * registry cannot resolve is precisely such a bypass.
+ *
+ * So the contract is the third option: **a callback tier never runs without a
+ * collection**, because a path that has none is refused before one can. That
+ * costs nothing, because it is already true — every read and every write
+ * reaches the database through `getCollectionByPath` in the driver's collection
+ * helpers, which raises this same "not found" for the same paths. Asking here
+ * only asks earlier, while the answer is still a 404 about the request instead
+ * of a `TypeError` attributed to the application's hook.
+ *
+ * @param collection The collection the driver resolved, if it resolved one.
+ * @param path       The collection path, for the message and `details`.
+ */
+export declare function requireCallbackCollection<C>(collection: C | undefined, path: string): C;
+/**
+ * The client a callback reads as `context.client` — or a refusal naming why
+ * there is none.
+ *
+ * A driver is constructed before the server client exists, and
+ * `initializeRebaseBackend` hands it the client afterwards. So a driver can
+ * run callbacks without one: constructed on its own, or missed by that
+ * injection, which is how a second database's callbacks once ran with
+ * `context.client === undefined` while the type said it was there.
+ *
+ * Called from a getter on the context rather than when the context is built,
+ * because most callbacks never touch `client` and must not fail for its
+ * absence. The one that does gets this sentence instead of "Cannot read
+ * properties of undefined". A 500, not the 400 `toCallbackError` makes of a
+ * plain throw: the callback is not at fault, the server's wiring is.
+ */
+export declare function requireCallbackClient<C>(client: C | undefined): C;

package/dist/util/index.d.ts

@@ -21,3 +21,4 @@ export * from "./conditions.js";
 export * from "./pg-column-to-property.js";
 export * from "./string-column-length.js";
 export * from "./internal-tables.js";
+export * from "./sql-rows.js";

package/dist/util/junction-policies.d.ts

@@ -103,6 +103,23 @@ export declare function resolveJunctionSpecs(collections: CollectionConfig[]): M
  * payload column anywhere is a second description that can disagree.
  */
 export declare function getJunctionCollectionConfig(spec: JunctionSpec): CollectionConfig;
+/**
+ * The same synthetic collection, reached from a resolved relation rather than
+ * from a spec.
+ *
+ * The spec is built by walking every collection, which the schema planner does
+ * once at boot and no request path can afford. A read or a write already holds
+ * the relation, and a relation's `through` carries the table, both key columns
+ * and the payload — everything the config is made of. One builder underneath
+ * both, so the shape the planner emitted columns from is the shape the write
+ * path validates a `_pivot` against and the read path strips it with.
+ */
+export declare function getJunctionConfigForRelation(through: {
+    table: string;
+    sourceColumn: string;
+    targetColumn: string;
+    properties: Properties;
+}): CollectionConfig;
 /**
  * Whether a parent-rule expression keeps its meaning when moved inside the
  * junction's `EXISTS` subquery — and the re-scoped copy if it does.

package/dist/util/sql-rows.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Read the rows out of whatever a SQL driver actually returned.
+ *
+ * Two shapes reach this repository's stores through the same call, and which
+ * one arrives is a property of the driver rather than of the query:
+ * node-postgres hands back a `{ rows }` envelope, and the other paths — a bare
+ * `executeSql`, Drizzle's `db.execute()` on some builds — hand back an array.
+ * `@rebasepro/server`'s `SqlExec` type declares the array, so the envelope is
+ * off-contract every time it turns up, and it still turns up.
+ *
+ * Reading one shape only is how a store silently sees nothing: the rate limiter
+ * that did it counted every caller as being on their first request — a limiter
+ * that never limits, with no error anywhere to say so.
+ *
+ * Written inline it came to `result as unknown as { rows?: T[] } | T[]`, five
+ * times across three packages. That is the problem restated as an assertion: a
+ * union the caller has to re-test at runtime anyway, with `unknown` in the
+ * middle only because neither half overlaps what the signature promised. The
+ * `Array.isArray` below is that same test done once, and it *narrows* — so
+ * these branches are checked rather than claimed.
+ *
+ * The element type is the one claim that stays a claim: these are rows from
+ * hand-written SQL, and nothing at this layer can check a column list.
+ */
+export declare function sqlRows<T = Record<string, unknown>>(result: unknown): T[];
+/** The first row of {@link sqlRows}, or `undefined` when there were none. */
+export declare function firstSqlRow<T = Record<string, unknown>>(result: unknown): T | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/common",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Rebase shared core — collection registry, data driver adapter and fluent query builder. No React dependency.",
   "keywords": [
     "rebase",
@@ -44,8 +44,8 @@
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.20.0",
-    "@rebasepro/utils": "0.20.0"
+    "@rebasepro/types": "0.21.0",
+    "@rebasepro/utils": "0.21.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",