@rebasepro/common 0.7.0 → 0.9.0

package/src/util/builders.ts

@@ -1,15 +1,18 @@
 import {
-    AdditionalFieldDelegate,
     ArrayProperty,
     BooleanProperty,
     DateProperty,
-    EntityCallbacks,
-    EntityCollection,
-    EnumValueConfig,
-    EnumValues,
+    CollectionConfig,
+    FirebaseCollectionConfig,
+    FirebaseProperties,
     GeopointProperty,
+    InferEntityType,
     MapProperty,
-    NumberProperty, Properties,
+    MongoDBCollectionConfig,
+    MongoProperties,
+    NumberProperty,
+    PostgresCollectionConfig,
+    PostgresProperties,
     Property,
     ReferenceProperty,
     StringProperty,
@@ -18,112 +21,112 @@ 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;
 }
 
-/**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the property keys.
- * @param property
- * @group Builder
- */
-export function buildProperty<T, P extends Property = Property>(
-    property: P
-):
-    P extends StringProperty ? StringProperty :
-    P extends NumberProperty ? NumberProperty :
-    P extends BooleanProperty ? BooleanProperty :
-    P extends DateProperty ? DateProperty :
-    P extends GeopointProperty ? GeopointProperty :
-    P extends ReferenceProperty ? ReferenceProperty :
-    P extends ArrayProperty ? ArrayProperty :
-    P extends MapProperty ? MapProperty : never {
-
-    // SAFETY: Identity function — P is a subtype of the conditional return type by definition
-    return property as unknown as ReturnType<typeof buildProperty<T, P>>;
-}
+// ── defineCollection ─────────────────────────────────────────────────────
+// A smarter builder that uses `const` type-parameter inference (TS 5.0+)
+// to capture literal property types automatically. This gives you
+// autocomplete on `titleProperty`, `sort`, `propertiesOrder`, `fixedFilter`,
+// callbacks, etc. — without writing `as const` or passing manual generics.
 
 /**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param properties
+ * Define a PostgreSQL-backed collection with full type inference.
+ *
+ * The `const P` generic captures literal property types from your
+ * `properties` object, which enables autocomplete on `titleProperty`,
+ * `sort`, `propertiesOrder`, `fixedFilter`, and entity callbacks.
+ *
+ * @example
+ * ```ts
+ * const products = defineCollection({
+ *     name: "Products",
+ *     slug: "products",
+ *     table: "products",
+ *     properties: {
+ *         name: { name: "Name", type: "string", validation: { required: true } },
+ *         price: { name: "Price", type: "number" },
+ *     },
+ *     titleProperty: "name",  // ✅ autocomplete: "name" | "price"
+ *     sort: ["price", "asc"], // ✅ autocomplete on first element
+ * });
+ * ```
+ *
  * @group Builder
  */
-export function buildProperties<M extends Record<string, unknown>>(
-    properties: Properties
-): Properties {
-    return properties;
-}
+export 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 };
 
 /**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param propertiesOrBuilder
+ * Define a Firestore-backed collection with full type inference.
  * @group Builder
  */
-export function buildPropertiesOrBuilder<M extends Record<string, unknown>>(
-    propertiesOrBuilder: Properties
-): Properties {
-    return propertiesOrBuilder;
-}
+export 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 };
 
 /**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param enumValues
+ * Define a MongoDB-backed collection with full type inference.
  * @group Builder
  */
-export function buildEnum(
-    enumValues: EnumValues
-): EnumValues {
-    return enumValues;
-}
+export 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 };
 
 /**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param enumValueConfig
- * @group Builder
+ * Implementation — delegates to the correct overload at the type level.
+ * At runtime this is a plain identity function.
  */
-export function buildEnumValueConfig(
-    enumValueConfig: EnumValueConfig
-): EnumValueConfig {
-    return enumValueConfig;
+export function defineCollection(
+    collection: CollectionConfig
+): CollectionConfig {
+    return collection;
 }
 
 /**
- * Identity function we use to defeat the type system of Typescript and preserve
- * the properties keys.
- * @param callbacks
+ * @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 buildEntityCallbacks<M extends Record<string, unknown> = Record<string, unknown>>(
-    callbacks: EntityCallbacks<M>
-): EntityCallbacks<M> {
-    return callbacks;
-}
+export function buildProperty<T, P extends Property = Property>(
+    property: P
+):
+    P extends StringProperty ? StringProperty :
+    P extends NumberProperty ? NumberProperty :
+    P extends BooleanProperty ? BooleanProperty :
+    P extends DateProperty ? DateProperty :
+    P extends GeopointProperty ? GeopointProperty :
+    P extends ReferenceProperty ? ReferenceProperty :
+    P extends ArrayProperty ? ArrayProperty :
+    P extends MapProperty ? MapProperty : never {
 
-/**
- * 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;
+    // SAFETY: Identity function — P is a subtype of the conditional return type by definition
+    return property as unknown as ReturnType<typeof buildProperty<T, P>>;
 }
-
-

package/src/util/callbacks.ts

@@ -1,4 +1,11 @@
-import { EntityCallbacks, Properties } from "@rebasepro/types";
+import { CollectionCallbacks, Properties, RebaseCallContext } from "@rebasepro/types";
+
+/**
+ * Context passed to entity lifecycle callbacks.
+ * @group Models
+ */
+export type EntityCallbackContext = RebaseCallContext;
+
 
 /**
  * Helper function to recursively check if there are any callbacks in the properties.
@@ -78,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/index.ts

@@ -4,6 +4,7 @@ export * from "./entities";
 export * from "./enums";
 export * from "./paths";
 export * from "./resolutions";
+export * from "./policy";
 export * from "./permissions";
 export * from "./references";
 export * from "./navigation_from_path";
@@ -14,3 +15,4 @@ export * from "./callbacks";
 export * from "./relations";
 export * from "./conditions";
 export * from "./navigation_utils";
+export * from "./filter-operator-resolution";

package/src/util/navigation_from_path.ts

@@ -1,4 +1,4 @@
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 type EntityCustomView<M extends Record<string, unknown> = Record<string, unknown>> = { key: string; [key: string]: unknown };
 import { getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
 import { getSubcollections } from "./resolutions";
@@ -13,7 +13,7 @@ export interface NavigationViewEntityInternal<M extends Record<string, unknown>>
     entityId: string | number;
     slug: string;
     path: string;
-    parentCollection: EntityCollection<M>;
+    parentCollection: CollectionConfig<M>;
 }
 
 export interface NavigationViewCollectionInternal<M extends Record<string, unknown>> {
@@ -21,7 +21,7 @@ export interface NavigationViewCollectionInternal<M extends Record<string, unkno
     id: string;
     slug: string;
     path: string;
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
 }
 
 export interface NavigationViewEntityCustomInternal<M extends Record<string, unknown>> {
@@ -34,7 +34,7 @@ export interface NavigationViewEntityCustomInternal<M extends Record<string, unk
 
 export function getNavigationEntriesFromPath(props: {
     path: string,
-    collections: EntityCollection[] | undefined,
+    collections: CollectionConfig[] | undefined,
     currentFullPath?: string,
     contextEntityViews?: EntityCustomView[]
 }): NavigationViewInternal[] {

package/src/util/navigation_utils.ts

@@ -1,4 +1,4 @@
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 
 import { getSubcollections } from "./resolutions";
 
@@ -33,13 +33,13 @@ export function getLastSegment(path: string) {
     return cleanPath;
 }
 
-export function resolveCollectionPathIds(path: string, allCollections: EntityCollection[]): string {
+export function resolveCollectionPathIds(path: string, allCollections: CollectionConfig[]): string {
     let remainingPath = removeInitialAndTrailingSlashes(path);
     if (!remainingPath) {
         return "";
     }
 
-    let currentCollections: EntityCollection[] | undefined = allCollections;
+    let currentCollections: CollectionConfig[] | undefined = allCollections;
     const resolvedPathParts: string[] = [];
 
     while (remainingPath.length > 0) {
@@ -53,7 +53,7 @@ export function resolveCollectionPathIds(path: string, allCollections: EntityCol
 
         let foundMatch = false;
         // Sort potential matches by length descending to prioritize longer matches (e.g., "a/b" over "a")
-        const potentialMatches: { col: EntityCollection; match: string; }[] = currentCollections
+        const potentialMatches: { col: CollectionConfig; match: string; }[] = currentCollections
             .flatMap(col => [{
                 col,
                 match: col.slug
@@ -76,7 +76,7 @@ export function resolveCollectionPathIds(path: string, allCollections: EntityCol
                 break; // Path ends with a collection segment
             }
 
-            // The next segment must be an entity ID
+            // The next segment must be a entity ID
             const idSeparatorIndex = remainingPath.indexOf("/");
             let entityId: string | number;
             if (idSeparatorIndex > -1) {
@@ -87,7 +87,7 @@ export function resolveCollectionPathIds(path: string, allCollections: EntityCol
                 // but handle it defensively: assume the rest is the ID
                 entityId = remainingPath;
                 remainingPath = "";
-                console.warn(`resolveCollectionPathIds: Path seems to end with an entity ID "${entityId}" instead of a collection segment in original path "${path}". This might indicate an invalid input path.`);
+                console.warn(`resolveCollectionPathIds: Path seems to end with a entity ID "${entityId}" instead of a collection segment in original path "${path}". This might indicate an invalid input path.`);
                 // Even if it ends here, we still need to push the ID
             }
 
@@ -123,7 +123,7 @@ export function resolveCollectionPathIds(path: string, allCollections: EntityCol
  * @param slugOrPath
  * @param collections
  */
-export function getCollectionBySlugWithin(slugOrPath: string, collections: EntityCollection[]): EntityCollection | undefined {
+export function getCollectionBySlugWithin(slugOrPath: string, collections: CollectionConfig[]): CollectionConfig | undefined {
 
     const subpaths = removeInitialAndTrailingSlashes(slugOrPath).split("/");
     if (subpaths.length % 2 === 0) {
@@ -131,7 +131,7 @@ export function getCollectionBySlugWithin(slugOrPath: string, collections: Entit
     }
 
     const subpathCombinations = getCollectionPathsCombinations(subpaths);
-    let result: EntityCollection | undefined;
+    let result: CollectionConfig | undefined;
     for (let i = 0; i < subpathCombinations.length; i++) {
         const subpathCombination = subpathCombinations[i];
         const navigationEntry = collections && collections

package/src/util/parent_references_from_path.ts

@@ -1,10 +1,10 @@
-import { EntityCollection, EntityReference } from "@rebasepro/types";
+import { CollectionConfig, EntityReference } from "@rebasepro/types";
 import { getCollectionPathsCombinations, removeInitialAndTrailingSlashes } from "./navigation_utils";
 import { getSubcollections } from "./resolutions";
 
 export function getParentReferencesFromPath(props: {
     path: string,
-    collections: EntityCollection[] | undefined,
+    collections: CollectionConfig[] | undefined,
     currentFullPath?: string,
 }): EntityReference[] {
 
@@ -21,7 +21,7 @@ export function getParentReferencesFromPath(props: {
     for (let i = 0; i < subpathCombinations.length; i++) {
         const subpathCombination = subpathCombinations[i];
 
-        const collection: EntityCollection | undefined = collections && collections.find((entry) => entry.slug === subpathCombination);
+        const collection: CollectionConfig | undefined = collections && collections.find((entry) => entry.slug === subpathCombination);
 
         // If we find a collection, we add the reference and continue
         if (collection) {

package/src/util/permissions.test.ts

@@ -1,5 +1,5 @@
 import { canCreateEntity, canEditEntity, canDeleteEntity, canReadCollection } from "./permissions";
-import { EntityCollection, AuthController, Entity, User, SecurityRule } from "@rebasepro/types";
+import { CollectionConfig, AuthController, Entity, User, SecurityRule } from "@rebasepro/types";
 
 describe("Permissions Evaluator", () => {
 
@@ -46,7 +46,7 @@ describe("Permissions Evaluator", () => {
         user: null
     };
 
-    const createMockCollection = (rules?: SecurityRule[]): EntityCollection => ({
+    const createMockCollection = (rules?: SecurityRule[]): CollectionConfig => ({
         slug: "test",
         name: "Test",
         table: "test",
@@ -162,9 +162,10 @@ roles: ["author"] }
         expect(canReadCollection(collection, mockAuthController)).toBe(true);
     });
 
-    test("11. Empty roles array [] on rule grants access to everyone (public)", () => {
+    test("11. Empty roles array [] adds no role restriction (public rule stays public)", () => {
         const collection = createMockCollection([
             { operation: "insert",
+access: "public",
 roles: [] }
         ]);
         expect(canCreateEntity(collection, mockAuthController, "test", null)).toBe(true);
@@ -172,9 +173,10 @@ roles: [] }
         expect(canCreateEntity(collection, adminAuthController, "test", null)).toBe(true);
     });
 
-    test("12. Undefined roles on rule grants access to everyone (public)", () => {
+    test("12. Undefined roles on a public rule grants access to everyone", () => {
         const collection = createMockCollection([
-            { operation: "insert" }
+            { operation: "insert",
+access: "public" }
         ]);
         expect(canCreateEntity(collection, mockAuthController, "test", null)).toBe(true);
         expect(canCreateEntity(collection, unauthenticatedController, "test", null)).toBe(true);