@rebasepro/common 0.8.0 → 0.9.1-canary.09aaf62

package/src/util/builders.ts

@@ -1,23 +1,18 @@
 import {
-    AdditionalFieldDelegate,
     ArrayProperty,
     BooleanProperty,
     DateProperty,
-    EntityCallbacks,
-    EntityCollection,
-    EnumValueConfig,
-    EnumValues,
-    FirebaseCollection,
+    CollectionConfig,
+    FirebaseCollectionConfig,
     FirebaseProperties,
     GeopointProperty,
     InferEntityType,
     MapProperty,
-    MongoDBCollection,
+    MongoDBCollectionConfig,
     MongoProperties,
     NumberProperty,
-    PostgresCollection,
+    PostgresCollectionConfig,
     PostgresProperties,
-    Properties,
     Property,
     ReferenceProperty,
     StringProperty,
@@ -26,17 +21,20 @@ import {
 
 
 /**
- * Identity function we use to defeat the type system of Typescript and build
- * collection views with all its properties
- * @param collection
+ * @deprecated Use {@link defineCollection} instead — it infers property
+ * types automatically (autocomplete on `titleProperty`, `sort`,
+ * `propertiesOrder`, callbacks) without manual generics.
+ * `buildCollection` is kept for FireCMS migration compatibility and will
+ * be removed before 1.0.
+ *
  * @group Builder
  */
 export function buildCollection<
     M extends Record<string, unknown> = Record<string, unknown>,
     USER extends User = User>
     (
-        collection: EntityCollection<M, USER>
-    ): EntityCollection<M, USER> {
+        collection: CollectionConfig<M, USER>
+    ): CollectionConfig<M, USER> {
     return collection;
 }
 
@@ -74,8 +72,8 @@ export function defineCollection<
     const P extends PostgresProperties,
     USER extends User = User
 >(
-    collection: Omit<PostgresCollection<InferEntityType<P>, USER>, "properties"> & { properties: P }
-): PostgresCollection<InferEntityType<P>, USER> & { properties: P };
+    collection: Omit<PostgresCollectionConfig<InferEntityType<P>, USER>, "properties"> & { properties: P }
+): PostgresCollectionConfig<InferEntityType<P>, USER> & { properties: P };
 
 /**
  * Define a Firestore-backed collection with full type inference.
@@ -85,8 +83,8 @@ export function defineCollection<
     const P extends FirebaseProperties,
     USER extends User = User
 >(
-    collection: Omit<FirebaseCollection<InferEntityType<P>, USER>, "properties"> & { properties: P }
-): FirebaseCollection<InferEntityType<P>, USER> & { properties: P };
+    collection: Omit<FirebaseCollectionConfig<InferEntityType<P>, USER>, "properties"> & { properties: P }
+): FirebaseCollectionConfig<InferEntityType<P>, USER> & { properties: P };
 
 /**
  * Define a MongoDB-backed collection with full type inference.
@@ -96,23 +94,25 @@ export function defineCollection<
     const P extends MongoProperties,
     USER extends User = User
 >(
-    collection: Omit<MongoDBCollection<InferEntityType<P>, USER>, "properties"> & { properties: P }
-): MongoDBCollection<InferEntityType<P>, USER> & { properties: P };
+    collection: Omit<MongoDBCollectionConfig<InferEntityType<P>, USER>, "properties"> & { properties: P }
+): MongoDBCollectionConfig<InferEntityType<P>, USER> & { properties: P };
 
 /**
  * Implementation — delegates to the correct overload at the type level.
  * At runtime this is a plain identity function.
  */
 export function defineCollection(
-    collection: EntityCollection
-): EntityCollection {
+    collection: CollectionConfig
+): CollectionConfig {
     return collection;
 }
 
 /**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the property keys.
- * @param property
+ * @deprecated Use plain typed property objects with {@link defineCollection}
+ * instead — `defineCollection` infers property types automatically, making
+ * this wrapper unnecessary. `buildProperty` is kept for FireCMS migration
+ * compatibility and will be removed before 1.0.
+ *
  * @group Builder
  */
 export function buildProperty<T, P extends Property = Property>(
@@ -130,77 +130,3 @@ export function buildProperty<T, P extends Property = Property>(
     // SAFETY: Identity function — P is a subtype of the conditional return type by definition
     return property as unknown as ReturnType<typeof buildProperty<T, P>>;
 }
-
-/**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param properties
- * @group Builder
- */
-export function buildProperties<M extends Record<string, unknown>>(
-    properties: Properties
-): Properties {
-    return properties;
-}
-
-/**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param propertiesOrBuilder
- * @group Builder
- */
-export function buildPropertiesOrBuilder<M extends Record<string, unknown>>(
-    propertiesOrBuilder: Properties
-): Properties {
-    return propertiesOrBuilder;
-}
-
-/**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param enumValues
- * @group Builder
- */
-export function buildEnum(
-    enumValues: EnumValues
-): EnumValues {
-    return enumValues;
-}
-
-/**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param enumValueConfig
- * @group Builder
- */
-export function buildEnumValueConfig(
-    enumValueConfig: EnumValueConfig
-): EnumValueConfig {
-    return enumValueConfig;
-}
-
-/**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param callbacks
- * @group Builder
- */
-export function buildEntityCallbacks<M extends Record<string, unknown> = Record<string, unknown>>(
-    callbacks: EntityCallbacks<M>
-): EntityCallbacks<M> {
-    return callbacks;
-}
-
-/**
- * Identity function we use to defeat the type system of Typescript and build
- * additional field delegates views with all its properties
- * @param additionalFieldDelegate
- * @group Builder
- */
-export function buildAdditionalFieldDelegate<M extends Record<string, unknown>, USER extends User = User>(
-    additionalFieldDelegate: AdditionalFieldDelegate<M, USER>
-): AdditionalFieldDelegate<M, USER> {
-    return additionalFieldDelegate;
-}
-
-

package/src/util/callbacks.ts

@@ -1,4 +1,4 @@
-import { EntityCallbacks, Properties, RebaseCallContext } from "@rebasepro/types";
+import { CollectionCallbacks, Properties, RebaseCallContext } from "@rebasepro/types";
 
 /**
  * Context passed to entity lifecycle callbacks.
@@ -85,24 +85,24 @@ async function processProperties(
 
 /**
  * Helper function to extract field-level PropertyCallbacks from a properties schema
- * and wrap them into an EntityCallbacks object recursively.
+ * and wrap them into an CollectionCallbacks object recursively.
  */
-export const buildPropertyCallbacks = (properties: Properties): EntityCallbacks | undefined => {
+export const buildPropertyCallbacks = (properties: Properties): CollectionCallbacks | undefined => {
     if (!properties) return undefined;
 
-    const propertyCallbacks: EntityCallbacks = {};
+    const propertyCallbacks: CollectionCallbacks = {};
 
     if (hasPropertyCallbacks(properties, "afterRead")) {
         propertyCallbacks.afterRead = async (props) => {
+            const row = props.row;
             const processedValues = await processProperties(
                 properties,
-                props.entity.values as Record<string, unknown>,
-                props.entity.values as Record<string, unknown>,
+                row,
+                row,
                 props as unknown,
                 "afterRead"
             );
-            return { ...props.entity,
-values: processedValues };
+            return { ...props.row, ...processedValues };
         };
     }
 

package/src/util/collections.ts

@@ -1,7 +1,7 @@
 import {
     DefaultSelectedViewBuilder,
     DefaultSelectedViewParams,
-    EntityCollection,
+    CollectionConfig,
     Properties,
     Property
 } from "@rebasepro/types";
@@ -99,7 +99,7 @@ export function resolveDefaultSelectedView(
 }
 
 
-export function getLocalChangesBackup(collection: EntityCollection) {
+export function getLocalChangesBackup(collection: CollectionConfig) {
     if (!collection.localChangesBackup) {
         return "manual_apply";
     }
@@ -108,12 +108,12 @@ export function getLocalChangesBackup(collection: EntityCollection) {
 }
 
 /**
- * Returns the primary keys for an entity collection by inspecting the properties
+ * Returns the primary keys for a entity collection by inspecting the properties
  * and finding any properties with `isId`.
  * Fallbacks to `["id"]` if no properties are marked as `isId: true`.
  * @param collection
  */
-export function getPrimaryKeys<M extends Record<string, unknown>>(collection: EntityCollection<M>): Extract<keyof M, string>[] {
+export function getPrimaryKeys<M extends Record<string, unknown>>(collection: CollectionConfig<M>): Extract<keyof M, string>[] {
     const properties = collection.properties;
     if (!properties) {
         return ["id"] as Extract<keyof M, string>[];

package/src/util/entities.ts

@@ -81,7 +81,7 @@ export function getDefaultValueFortype(type: DataType): unknown {
 }
 
 /**
- * Update the automatic values in an entity before save
+ * Update the automatic values in a entity before save
  * @group Driver
  */
 export function updateDateAutoValues<M extends Record<string, unknown>>({
@@ -117,7 +117,7 @@ export function updateDateAutoValues<M extends Record<string, unknown>>({
 }
 
 /**
- * Add missing required fields, expected in the collection, to the values of an entity
+ * Add missing required fields, expected in the collection, to the values of a entity
  * @param values
  * @param properties
  * @group Driver
@@ -148,7 +148,7 @@ export function getReferenceFrom<M extends Record<string, unknown>>(entity: Enti
 }
 
 export function getRelationFrom<M extends Record<string, unknown>>(entity: Entity<M>): EntityRelation {
-    return new EntityRelation(entity.id, entity.path, entity);
+    return new EntityRelation(entity.id, entity.path, entity as unknown as Record<string, unknown>);
 }
 
 /**
@@ -179,7 +179,7 @@ export function normalizeToEntityRelation(value: unknown, propertyType?: string)
     return new EntityRelation(
         obj.id as string | number,
         obj.path as string,
-        obj.data as Entity | undefined
+        obj.data as Record<string, unknown> | undefined
     );
 }
 

package/src/util/filter-operator-resolution.ts

@@ -0,0 +1,81 @@
+import {
+    ALL_WHERE_FILTER_OPS,
+    DataType,
+    getDataSourceCapabilities,
+    Property,
+    WhereFilterOp
+} from "@rebasepro/types";
+
+/**
+ * Default operators offered per property type, before engine capabilities and
+ * per-property narrowing are applied. These mirror what the built-in filter
+ * fields can render.
+ */
+const COMPARISON_OPS: readonly WhereFilterOp[] = ["==", "!=", ">", ">=", "<", "<="];
+const NULL_CHECK_OPS: readonly WhereFilterOp[] = ["is-null", "is-not-null"];
+const MEMBERSHIP_OPS: readonly WhereFilterOp[] = ["in", "not-in"];
+const PATTERN_OPS: readonly WhereFilterOp[] = ["like", "ilike", "not-like", "not-ilike"];
+
+const DEFAULT_OPS_BY_TYPE: Partial<Record<DataType, readonly WhereFilterOp[]>> = {
+    string: [...COMPARISON_OPS, ...MEMBERSHIP_OPS, ...PATTERN_OPS, ...NULL_CHECK_OPS],
+    number: [...COMPARISON_OPS, ...MEMBERSHIP_OPS, ...NULL_CHECK_OPS],
+    date: [...COMPARISON_OPS, ...NULL_CHECK_OPS],
+    boolean: ["==", "!=", ...NULL_CHECK_OPS],
+    reference: ["==", "!=", ...MEMBERSHIP_OPS, ...NULL_CHECK_OPS],
+    relation: ["==", "!=", ...MEMBERSHIP_OPS, ...NULL_CHECK_OPS]
+    // geopoint, map, vector, binary, array (as a container): not filterable
+    // through the generic filter UI.
+};
+
+/** Operators offered when the property is an *array of* a filterable type. */
+const ARRAY_OPS: readonly WhereFilterOp[] = ["array-contains", "array-contains-any"];
+
+export interface ResolveFilterOperatorsParams {
+    /**
+     * The property to filter on. For array properties, pass the **item**
+     * property (`property.of`) together with `isArray: true` — the same
+     * convention the filter field dispatchers use.
+     */
+    property: Property;
+    /** True when filtering an array of `property`. */
+    isArray?: boolean;
+    /**
+     * The engine backing the collection (`collection.engine`, e.g.
+     * `"postgres"`, `"firestore"`). Falls back to the default engine's
+     * capabilities when omitted.
+     */
+    engine?: string;
+}
+
+/**
+ * Resolve which filter operators the UI should offer for a property.
+ *
+ * The result is the **intersection** of three sets:
+ * 1. what the engine can execute — {@link DataSourceCapabilities.filterOperators}
+ *    (e.g. Firestore cannot run the LIKE family);
+ * 2. what makes sense for the property type (e.g. no `>` on booleans);
+ * 3. the developer's optional narrowing — `property.ui.filterOperators`.
+ *
+ * Returns an empty array when the property is not filterable (either by
+ * type, or because the developer disabled it with `filterOperators: []`).
+ *
+ * @group Models
+ */
+export function resolveFilterOperators({
+    property,
+    isArray,
+    engine
+}: ResolveFilterOperatorsParams): WhereFilterOp[] {
+    const typeDefaults: readonly WhereFilterOp[] = isArray
+        ? ARRAY_OPS
+        : DEFAULT_OPS_BY_TYPE[property.type] ?? [];
+    if (typeDefaults.length === 0) return [];
+
+    const engineOps = new Set(getDataSourceCapabilities(engine).filterOperators ?? ALL_WHERE_FILTER_OPS);
+
+    const narrowing = property.ui?.filterOperators;
+    const narrowingSet = narrowing !== undefined ? new Set(narrowing) : undefined;
+
+    return typeDefaults.filter(op =>
+        engineOps.has(op) && (narrowingSet === undefined || narrowingSet.has(op)));
+}

package/src/util/identity.ts

@@ -0,0 +1,166 @@
+/**
+ * Row identity: the address of a row, and how to derive it.
+ *
+ * Postgres has no `id`. A row is identified by its primary key — one or more
+ * columns, with any names and any types. `id` is something we synthesize on top
+ * of that: a single string token, because the admin needs *one* value it can put
+ * in a URL (`/products/1:::2`), use as a cache key, and hang a relation ref off.
+ *
+ * That token is an address, not data. It is derived from the row's columns and
+ * never stored in them — a row is exactly its columns, with their real types.
+ * Writing the address back into the row is what used to rename primary keys
+ * (`sku` → `id`) and restringify them (`42` → `"42"`) on the way out.
+ *
+ * These live in `common` because both sides need them and must agree exactly:
+ * the driver parses an incoming address back into key columns, and the admin
+ * derives the address from a row it was served.
+ */
+
+/**
+ * A primary-key column: its name, the type it round-trips as, and whether it is
+ * a UUID (which is a string despite sometimes being described as an id "number").
+ */
+export interface PrimaryKeyInfo {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}
+
+/** Separator between the parts of a composite address. */
+export const COMPOSITE_ID_SEPARATOR = ":::";
+
+/**
+ * Derive a row's address from its key columns.
+ *
+ * Single key → the value as a string. Composite → each part joined by
+ * {@link COMPOSITE_ID_SEPARATOR}, in primary-key order, which is what
+ * {@link parseIdValues} expects to invert.
+ */
+export function buildCompositeId(values: Record<string, unknown>, primaryKeys: PrimaryKeyInfo[]): string {
+    if (primaryKeys.length === 0) {
+        return "";
+    }
+    if (primaryKeys.length === 1) {
+        return String(values[primaryKeys[0].fieldName] ?? "");
+    }
+    return primaryKeys.map(pk => String(values[pk.fieldName] ?? "")).join(COMPOSITE_ID_SEPARATOR);
+}
+
+/**
+ * Invert {@link buildCompositeId}: turn an address back into key columns, each
+ * coerced to the type its column actually round-trips as.
+ *
+ * This is the boundary where a URL segment becomes a query parameter, so a
+ * malformed address must throw rather than silently produce a query that
+ * matches the wrong row (or none).
+ */
+export function parseIdValues(idValue: string | number, primaryKeys: PrimaryKeyInfo[]): Record<string, string | number> {
+    const result: Record<string, string | number> = {};
+
+    if (primaryKeys.length === 0) {
+        return result;
+    }
+
+    if (primaryKeys.length === 1) {
+        const pk = primaryKeys[0];
+        if (pk.type === "number" && !pk.isUUID) {
+            const parsed = typeof idValue === "number" ? idValue : parseInt(String(idValue), 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid numeric ID: ${idValue}`);
+            }
+            result[pk.fieldName] = parsed;
+        } else {
+            result[pk.fieldName] = String(idValue);
+        }
+        return result;
+    }
+
+    // Composite key
+    const parts = String(idValue).split(COMPOSITE_ID_SEPARATOR);
+    if (parts.length !== primaryKeys.length) {
+        throw new Error(`Composite ID parts mismatch. Expected ${primaryKeys.length}, got ${parts.length} for ID: ${idValue}`);
+    }
+
+    for (let i = 0; i < primaryKeys.length; i++) {
+        const pk = primaryKeys[i];
+        const val = parts[i];
+        if (pk.type === "number" && !pk.isUUID) {
+            const parsed = parseInt(val, 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid numeric ID component: ${val}`);
+            }
+            result[pk.fieldName] = parsed;
+        } else {
+            result[pk.fieldName] = val;
+        }
+    }
+
+    return result;
+}
+
+/**
+ * The primary keys of a collection, as declared by its properties.
+ *
+ * This is the only tier both sides can read, because it is the only one written
+ * in the config: the postgres driver can also infer keys from the Drizzle
+ * schema, which the browser never sees and is never sent — the admin compiles
+ * the collection files into its own bundle rather than being served them. A key
+ * that lives only in the Drizzle schema is therefore invisible here, and the
+ * server says so at boot (`warnOnKeysTheAdminCannotResolve`) naming the `isId`
+ * to add.
+ *
+ * Returns an empty array when a collection declares none, which callers must
+ * treat as "not addressable" rather than defaulting to `id`: guessing a key
+ * that is not the real one produces confidently wrong addresses.
+ */
+export function getDeclaredPrimaryKeys(collection: {
+    properties?: Record<string, unknown>;
+}): PrimaryKeyInfo[] {
+    const properties = collection.properties;
+    if (!properties) return [];
+
+    const keys: PrimaryKeyInfo[] = [];
+    for (const [fieldName, propRaw] of Object.entries(properties)) {
+        const prop = propRaw as { type?: string; isId?: unknown } | undefined;
+        if (!prop || typeof prop !== "object") continue;
+        if (!("isId" in prop) || !prop.isId) continue;
+        keys.push({
+            fieldName,
+            type: prop.type === "number" ? "number" : "string",
+            isUUID: prop.isId === "uuid"
+        });
+    }
+    return keys;
+}
+
+/**
+ * The keys to address a collection's rows with, resolved the way the driver
+ * resolves them — minus the tier the browser cannot reach.
+ *
+ * The postgres driver tries, in order: properties marked `isId`; the primary
+ * keys of the Drizzle schema; and finally a column literally named `id`. Only
+ * the first and last are visible in a `CollectionConfig`, which is what both
+ * sides share.
+ *
+ * So the two agree except on a collection that declares no `isId` and whose key
+ * is known only to Drizzle. There, the driver reads the real key, and this
+ * either resolves nothing (reported to the console by the caller) or — if the
+ * table happens to have an unrelated `id` property — resolves `id`, which is
+ * the wrong key and cannot be detected from here: the addresses look right and
+ * route wrong. Only the config can settle it, so the server names both cases
+ * at boot (`warnOnKeysTheAdminCannotResolve`) with the `isId` to add.
+ */
+export function resolvePrimaryKeys(collection: {
+    properties?: Record<string, unknown>;
+}): PrimaryKeyInfo[] {
+    const declared = getDeclaredPrimaryKeys(collection);
+    if (declared.length > 0) return declared;
+
+    const idProp = collection.properties?.id as { type?: string } | undefined;
+    if (idProp && typeof idProp === "object") {
+        return [{ fieldName: "id",
+type: idProp.type === "number" ? "number" : "string" }];
+    }
+
+    return [];
+}

package/src/util/index.ts

@@ -1,6 +1,7 @@
 export * from "./collections";
 export * from "./common";
 export * from "./entities";
+export * from "./identity";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
@@ -13,5 +14,8 @@ export * from "./builders";
 export * from "./storage";
 export * from "./callbacks";
 export * from "./relations";
+export * from "./auth-default-policies";
+export * from "./junction-policies";
 export * from "./conditions";
 export * from "./navigation_utils";
+export * from "./filter-operator-resolution";