@rebasepro/common 0.8.0 → 0.9.0

package/README.md

@@ -15,7 +15,7 @@ pnpm add @rebasepro/common
 - **Collection utilities** — collection registry, default collection definitions, path resolution, navigation helpers
 - **Data driver adapter** — `buildRebaseData()` bridges any `DataDriver` implementation into a `RebaseData` proxy with typed collection accessors
 - **Query builder** — fluent `QueryBuilder` class plus `or()`, `and()`, `cond()` helpers for composing complex queries
-- **Entity/property utilities** — entity resolution, enum helpers, permission checks, reference/relation helpers, storage path utils, callback utilities
+- **Snapshot/property utilities** — snapshot resolution, enum helpers, permission checks, reference/relation helpers, storage path utils, callback utilities
 
 This package has no React dependency — it's pure TypeScript and can be used in both client and server contexts.
 
@@ -44,7 +44,7 @@ This package has no React dependency — it's pure TypeScript and can be used in
 |---|---|
 | `collections` | Collection config helpers |
 | `common` | General-purpose utilities |
-| `entities` | Entity value resolution |
+| `snapshots` | Snapshot value resolution |
 | `enums` | Enum type helpers |
 | `paths` | Path parsing and manipulation |
 | `resolutions` | Property and collection resolution |
@@ -69,7 +69,7 @@ const data = buildRebaseData(myDriver);
 
 // Access collections by name (camelCase auto-converts to snake_case)
 const { data: products } = await data.products.find({ limit: 10 });
-const entity = await data.products.findById("abc-123");
+const snapshot = await data.products.findById("abc-123");
 
 // Fluent query builder
 const { data: results } = await data.products
@@ -89,7 +89,7 @@ const { data: filtered } = await data.products
 
 ## Related Packages
 
-- [`@rebasepro/types`](../types) — `DataDriver`, `RebaseData`, `CollectionAccessor`, `Entity`, `FindResponse`, etc.
+- [`@rebasepro/types`](../types) — `DataDriver`, `RebaseData`, `CollectionAccessor`, `Snapshot`, `FindResponse`, etc.
 - [`@rebasepro/utils`](../utils) — Low-level utilities (`toSnakeCase`, etc.)
 - [`@rebasepro/core`](../core) — Runtime layer that consumes `@rebasepro/common`
 - [`@rebasepro/client`](../client) — HTTP client that re-exports and extends the `QueryBuilder`

package/dist/collections/CollectionRegistry.d.ts

@@ -1,4 +1,4 @@
-import { EntityCallbacks, EntityCollection } from "@rebasepro/types";
+import { CollectionCallbacks, CollectionConfig } from "@rebasepro/types";
 import { DataSourceRegistry } from "../data/resolveDataSource";
 export declare class CollectionRegistry {
     /**
@@ -17,11 +17,11 @@ export declare class CollectionRegistry {
      * Set global lifecycle callbacks that apply to every collection.
      * Typically called once during backend initialization.
      */
-    setGlobalCallbacks(callbacks: EntityCallbacks): void;
+    setGlobalCallbacks(callbacks: CollectionCallbacks): void;
     /**
      * Get the currently registered global callbacks, if any.
      */
-    getGlobalCallbacks(): EntityCallbacks | undefined;
+    getGlobalCallbacks(): CollectionCallbacks | undefined;
     private collectionsByTableName;
     private collectionsBySlug;
     private rootCollections;
@@ -30,8 +30,8 @@ export declare class CollectionRegistry {
     private rawCollectionsBySlug;
     private rawRootCollections;
     private cachedRawCollectionsList;
-    private lastRawInputSnapshot;
-    constructor(collections?: EntityCollection[], dataSources?: DataSourceRegistry);
+    private lastRawInputEntity;
+    constructor(collections?: CollectionConfig[], dataSources?: DataSourceRegistry);
     /**
      * Provide the declared data sources used to resolve each collection's
      * engine during normalization. Set this before registering collections.
@@ -44,13 +44,13 @@ export declare class CollectionRegistry {
      * Returns true if the collections have changed, false otherwise.
      *
      * Idempotent: compares the raw input (before normalization) against a stored
-     * snapshot. Only re-normalizes and re-registers when the raw input actually changed.
+     * entity. Only re-normalizes and re-registers when the raw input actually changed.
      * @param collections
      */
-    registerMultiple(collections: EntityCollection[]): boolean;
-    register(collection: EntityCollection, rawCollection?: EntityCollection): void;
+    registerMultiple(collections: CollectionConfig[]): boolean;
+    register(collection: CollectionConfig, rawCollection?: CollectionConfig): void;
     private _registerRecursively;
-    normalizeCollection(collection: EntityCollection): EntityCollection;
+    normalizeCollection(collection: CollectionConfig): CollectionConfig;
     /**
      * Extract Relation[] from properties that have inline relation config (i.e. `target` is set).
      * This allows developers to define relations directly on properties without a separate
@@ -59,26 +59,26 @@ export declare class CollectionRegistry {
     private extractRelationsFromProperties;
     private normalizeProperties;
     private normalizeProperty;
-    get(path: string): EntityCollection | undefined;
+    get(path: string): CollectionConfig | undefined;
     /**
      * Gets the pristine, un-normalized collection exactly as it was provided.
      * Useful for the AST editor so it doesn't accidentally serialize injected metadata back to disk.
      */
-    getRaw(path: string): EntityCollection | undefined;
+    getRaw(path: string): CollectionConfig | undefined;
     /**
      * Get collection by resolving multi-segment paths through relations
      * e.g., "authors/70/posts" resolves to the posts collection
      */
-    getCollectionByPath(collectionPath: string): EntityCollection | undefined;
-    getCollections(): EntityCollection[];
-    getRawCollections(): EntityCollection[];
+    getCollectionByPath(collectionPath: string): CollectionConfig | undefined;
+    getCollections(): CollectionConfig[];
+    getRawCollections(): CollectionConfig[];
     /**
      * Resolves a multi-segment path like "products/123/locales" and returns
      * information about the collections and entity IDs along the path
      */
     resolvePathToCollections(path: string): {
-        collections: EntityCollection[];
+        collections: CollectionConfig[];
         entityIds: (string | number)[];
-        finalCollection: EntityCollection;
+        finalCollection: CollectionConfig;
     };
 }

package/dist/collections/default-collections.d.ts

@@ -5,7 +5,7 @@
  * Slug-based dedup (Map keyed by slug, last-write-wins) lets developers
  * override by defining their own collection with `slug: "users"`.
  */
-export declare const defaultUsersCollection: import("@rebasepro/types").PostgresCollection<import("@rebasepro/types").InferEntityType<{
+export declare const defaultUsersCollection: import("@rebasepro/types").PostgresCollectionConfig<import("@rebasepro/types").InferEntityType<{
     readonly id: {
         readonly name: "ID";
         readonly type: "string";

package/dist/data/buildRebaseData.d.ts

@@ -1,4 +1,4 @@
-import { DataDriver, RebaseData } from "@rebasepro/types";
+import { DataDriver, RebaseData, RebaseSdkData } from "@rebasepro/types";
 /**
  * Build a `RebaseData` object from a `DataDriver` using JavaScript Proxy.
  *
@@ -9,6 +9,34 @@ import { DataDriver, RebaseData } from "@rebasepro/types";
  * @example
  * const data = buildRebaseData(driver);
  * await data.products.create({ name: "Camera", price: 299 });
- * const { data: items } = await data.products.find({ where: { status: "eq.published" } });
+ * const { data: items } = await data.products.find({ where: { status: ["==", "published"] } });
  */
 export declare function buildRebaseData(driver: DataDriver): RebaseData;
+/**
+ * Wrap a flat {@link RebaseSdkData} into a Entity-shaped {@link RebaseData}.
+ *
+ * This is the **CMS boundary**: the SDK client (`client.data`) returns flat
+ * rows, but the admin renders the `Entity` view-model (`entity.values.*`).
+ * `core/Rebase.tsx` wraps `client.data` through this before handing it to the
+ * CMS `RebaseDataContext` — without it the admin renders rows with only their
+ * `id`.
+ */
+export declare function wrapAsEntityData(sdkData: RebaseSdkData): RebaseData;
+/**
+ * Wrap a Entity-shaped {@link RebaseData} into a flat {@link RebaseSdkData}.
+ *
+ * Every collection accessor is adapted to return flat rows. Use this to derive
+ * the flat SDK data layer (`context.data`) from an existing Entity data layer
+ * — e.g. the admin routes its Entity data via `useData()` and exposes the
+ * same routing as flat `context.data` for callbacks by wrapping it here.
+ */
+export declare function wrapAsSdkData(entityData: RebaseData): RebaseSdkData;
+/**
+ * Build a flat {@link RebaseSdkData} from a `DataDriver`.
+ *
+ * This is the developer-facing SDK data layer used by backend framework
+ * callbacks & scripts (`context.data` / `rebase.data`). It returns flat rows —
+ * identical in shape to the frontend SDK client — so the API is symmetric
+ * across front and back. The admin CMS uses {@link buildRebaseData} (Entity).
+ */
+export declare function buildSdkData(driver: DataDriver): RebaseSdkData;

package/dist/data/buildRoutedRebaseData.d.ts

@@ -1,21 +1,26 @@
-import { RebaseData } from "@rebasepro/types";
+import { RebaseData, RebaseSdkData } from "@rebasepro/types";
+/**
+ * The two data-layer shapes that can be routed: the Entity-shaped admin
+ * {@link RebaseData} or the flat SDK {@link RebaseSdkData}. Both expose a
+ * `.collection(slug)` accessor, which is all the router needs.
+ */
+export type RoutableData = RebaseData | RebaseSdkData;
 /**
  * Parameters for {@link buildRoutedRebaseData}.
  */
-export interface RoutedRebaseDataParams {
+export interface RoutedRebaseDataParams<T extends RoutableData = RebaseData> {
     /**
      * The default data source. Handles every collection that does not
      * resolve to an entry in `sources` (i.e. server-transport collections,
      * which ride the Rebase client).
      */
-    defaultData: RebaseData;
+    defaultData: T;
     /**
-     * Per-data-source {@link RebaseData} instances for direct and custom
-     * transports, keyed by data-source key (e.g. `"analytics"`). Server-
-     * mediated sources are not listed here — they fall through to
-     * `defaultData`.
+     * Per-data-source instances for direct and custom transports, keyed by
+     * data-source key (e.g. `"analytics"`). Server-mediated sources are not
+     * listed here — they fall through to `defaultData`.
      */
-    sources: Record<string, RebaseData>;
+    sources: Record<string, T>;
     /**
      * Resolve the data-source key for a given collection slug or path.
      * Typically backed by the collection registry + `resolveDataSource`
@@ -50,4 +55,4 @@ export interface RoutedRebaseDataParams {
  * await data.products.find();        // → default (server / Postgres)
  * await data.events.find();          // → Firestore, if `events.dataSource === "analytics"`
  */
-export declare function buildRoutedRebaseData({ defaultData, sources, resolveKey }: RoutedRebaseDataParams): RebaseData;
+export declare function buildRoutedRebaseData<T extends RoutableData = RebaseData>({ defaultData, sources, resolveKey }: RoutedRebaseDataParams<T>): T;

package/dist/data/filter-dialect.d.ts

@@ -5,12 +5,22 @@
  * PostgREST-style dot-syntax strings (`eq.active`, `gt.18`, `in.(a,b)`).
  * Everything else speaks `FilterValues` exclusively.
  *
+ * Wire-format values are always strings — the wire format carries no type
+ * metadata, so type coercion is the responsibility of the server-side data
+ * driver which has access to the collection schema.
+ *
+ * Commas inside list values are backslash-escaped (`\,`), and literal
+ * backslashes are escaped as `\\`.
+ *
  * @module
  */
 import { FilterValues, LogicalCondition, FilterCondition } from "@rebasepro/types";
 /**
- * Convert `FilterValues` to a PostgREST-style querystring record.
+ * Convert `FilterValues` (or `WireFilterValues`) to a PostgREST-style
+ * querystring record.
  *
+ * - Canonical `[WhereFilterOp, value]` tuples are serialized strictly.
+ * - Pre-serialized PostgREST strings (e.g. `"eq.published"`) are passed through.
  * - Single conditions produce a string value.
  * - Multiple conditions on the same field produce a string array (repeated params).
  *
@@ -20,8 +30,12 @@ import { FilterValues, LogicalCondition, FilterCondition } from "@rebasepro/type
  *
  * serializeFilter({ age: [[">=", 18], ["<", 65]] })
  * // → { age: ["gte.18", "lt.65"] }
+ *
+ * // Pre-serialized strings pass through unchanged:
+ * serializeFilter({ status: "eq.published" })
+ * // → { status: "eq.published" }
  */
-export declare function serializeFilter(filter: FilterValues<string> | Record<string, any>): Record<string, string | string[]>;
+export declare function serializeFilter(filter: FilterValues<string> | Record<string, unknown>): Record<string, string | string[]>;
 /**
  * Convert a PostgREST-style querystring record to `FilterValues`.
  *
@@ -33,9 +47,9 @@ export declare function serializeFilter(filter: FilterValues<string> | Record<st
  * // → { status: ["==", "active"] }
  *
  * deserializeFilter({ age: ["gte.18", "lt.65"] })
- * // → { age: [[">=", 18], ["<", 65]] }
+ * // → { age: [[">=", "18"], ["<", "65"]] }
  */
-export declare function deserializeFilter(query: Record<string, any>): FilterValues<string>;
+export declare function deserializeFilter(query: Record<string, unknown>): FilterValues<string>;
 /**
  * Serialize a `LogicalCondition` or `FilterCondition` to its wire-format string.
  *

package/dist/data/query_builder.d.ts

@@ -1,4 +1,4 @@
-import { FindResponse, CollectionAccessor, QueryBuilderInterface, WhereFilterOp, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+import { CollectionAccessor, FilterCondition, FindResponse, LogicalCondition, QueryBuilderInterface, WhereFilterOp, WhereValue } from "@rebasepro/types";
 export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
 export declare function cond(column: string, operator: WhereFilterOp, value: unknown): FilterCondition;

package/dist/data/resolveDataSource.d.ts

@@ -1,7 +1,7 @@
 import { DataSourceDefinition, ResolvedDataSource } from "@rebasepro/types";
 /**
  * The subset of a collection needed to resolve its data source. Accepting a
- * structural type (rather than the full `EntityCollection`) keeps this usable
+ * structural type (rather than the full `CollectionConfig`) keeps this usable
  * from anywhere — frontend router, backend registry, editor — without coupling
  * to the collection union.
  */

package/dist/data/sort-dialect.d.ts

@@ -0,0 +1,41 @@
+import type { OrderByTuple } from "@rebasepro/types";
+/**
+ * Sort-order wire codec.
+ *
+ * This is the ONLY module that knows about the colon-delimited wire format
+ * (`"field:direction"`) used in HTTP query parameters.
+ * Everything else speaks {@link OrderByTuple} exclusively.
+ *
+ * Mirrors the filter architecture in `filter-dialect.ts`.
+ *
+ * @module
+ */
+/**
+ * Serialize an {@link OrderByTuple} to the wire format `"field:direction"`.
+ *
+ * **Runtime tolerance:** if the input is already a well-formed wire string
+ * (from an untyped JS caller), it is returned unchanged.
+ * This is undocumented tolerance, not public API — don't rely on it.
+ *
+ * @param orderBy - A canonical `[field, direction]` tuple, or at runtime
+ *   possibly a pre-serialized string (undocumented tolerance).
+ * @returns The wire-format string, or `undefined` if the input is falsy.
+ *
+ * @remarks
+ * Field names containing `:` are representable in the tuple form but
+ * **not** on the wire — this is an inherent limitation of the colon-delimited
+ * encoding and is not resolved here.
+ */
+export declare function serializeOrderBy(orderBy?: OrderByTuple | string): string | undefined;
+/**
+ * Deserialize a wire-format `"field:direction"` string into an {@link OrderByTuple}.
+ *
+ * Lenient parsing (matches existing server behaviour):
+ * - Bare field name (no colon): `"name"` → `["name", "asc"]`
+ * - Unknown direction: `"name:foo"` → `["name", "asc"]`
+ * - Empty / falsy input: → `undefined`
+ *
+ * @param raw - The wire-format string from an HTTP query parameter.
+ * @returns The canonical tuple, or `undefined` if the input is empty/falsy.
+ */
+export declare function deserializeOrderBy(raw?: string): OrderByTuple | undefined;

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from "./data/buildRoutedRebaseData";
 export * from "./data/resolveDataSource";
 export * from "./data/query_builder";
 export * from "./data/filter-dialect";
+export * from "./data/sort-dialect";
 export * from "./table-classification";