@rebasepro/common 0.7.0 → 0.9.0

package/src/util/policy/securityRuleToConditions.ts

@@ -0,0 +1,67 @@
+import { PolicyExpression, SecurityRule, policy } from "@rebasepro/types";
+import { sqlToPolicy } from "./sqlToPolicy";
+
+/**
+ * The normalized `USING` / `WITH CHECK` conditions for a single security rule,
+ * expressed in the engine-agnostic {@link PolicyExpression} model.
+ *
+ * A `null` clause means "this rule contributes no condition for that clause";
+ * consumers apply the default (Postgres denies with `false`).
+ */
+export interface RuleConditions {
+    usingExpr: PolicyExpression | null;
+    withCheckExpr: PolicyExpression | null;
+}
+
+/**
+ * Desugars a {@link SecurityRule} — its `access`/`ownerField`/`roles` shortcuts,
+ * structured `condition`/`check`, and raw `using`/`withCheck` — into a single
+ * normalized {@link PolicyExpression} pair.
+ *
+ * **This is the linchpin against drift:** both the Postgres DDL generators and
+ * the client-side evaluator consume this one function, so there is exactly one
+ * definition of what a rule means. In particular, application `roles` are folded
+ * into the expression here (AND'd with the base condition, matching how Postgres
+ * generates the clause) rather than being handled separately by each consumer.
+ */
+export function securityRuleToConditions(rule: SecurityRule): RuleConditions {
+    return {
+        usingExpr: withRoles(baseUsing(rule), rule),
+        withCheckExpr: withRoles(baseWithCheck(rule), rule)
+    };
+}
+
+function baseUsing(rule: SecurityRule): PolicyExpression | null {
+    if (rule.condition) return rule.condition;
+    if (rule.using != null) return sqlToPolicy(rule.using);
+    if (rule.access === "public") return policy.true();
+    if (rule.ownerField) return policy.compare(policy.field(rule.ownerField), "eq", policy.authUid());
+    return null;
+}
+
+function baseWithCheck(rule: SecurityRule): PolicyExpression | null {
+    if (rule.check) return rule.check;
+    if (rule.withCheck != null) return sqlToPolicy(rule.withCheck);
+    // No explicit WITH CHECK → fall back to the USING condition, matching
+    // PostgreSQL's own default behavior.
+    return baseUsing(rule);
+}
+
+/**
+ * AND the base condition with an application-role check, or produce a roles-only
+ * condition when there is no base. Mirrors the Postgres generator so that a
+ * role-scoped restrictive rule denies exactly the same set of users on both
+ * sides.
+ */
+function withRoles(base: PolicyExpression | null, rule: SecurityRule): PolicyExpression | null {
+    if (!rule.roles || rule.roles.length === 0) return base;
+    const rolesExpr = policy.rolesOverlap(rule.roles);
+    if (rule.mode === "restrictive") {
+        // Restrictive rule: applies ONLY if user has the roles.
+        // If user DOES NOT have the roles, they are NOT restricted (passes).
+        // If user HAS the roles, they must pass the base condition.
+        // Logical equivalent: NOT(roles) OR base
+        return base ? policy.or(policy.not(rolesExpr), base) : policy.not(rolesExpr);
+    }
+    return base ? policy.and(base, rolesExpr) : rolesExpr;
+}

package/src/util/policy/sqlToPolicy.ts

@@ -0,0 +1,88 @@
+import { PolicyExpression, policy } from "@rebasepro/types";
+
+/**
+ * A tiny, regex-based SQL "parser" for security rules.
+ *
+ * This is NOT a full SQL parser. It is designed to handle the subset of SQL
+ * commonly used in `USING` and `WITH CHECK` clauses, enough to drive the
+ * optimistic client-side UI decision.
+ *
+ * It handles:
+ * - `field = 'literal'`
+ * - `field != 'literal'`
+ * - `field = current_setting('app.user_id')`
+ * - `A AND B`
+ * - `true`
+ * - `IN (...)` (as optimistic true)
+ *
+ * For anything it doesn't understand, it returns a `raw` expression, which
+ * the evaluator treats as "unknown" (and usually optimistic true).
+ */
+export function sqlToPolicy(sql: string): PolicyExpression {
+    const trimmed = sql.trim();
+
+    if (trimmed.toLowerCase() === "true") return policy.true();
+    if (trimmed.toLowerCase() === "false") return policy.false();
+
+    // Handle roles overlap (&&)
+    // Matches: string_to_array(auth.roles(), ',') && ARRAY['admin', 'editor']
+    const overlapMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*&&\s*ARRAY\s*\[(.+)\]$/i);
+    if (overlapMatch) {
+        const roles = overlapMatch[1].split(",").map(s => s.trim().replace(/^'|'$/g, ""));
+        return policy.rolesOverlap(roles);
+    }
+
+    // Handle roles containment (@>)
+    // Matches: string_to_array(auth.roles(), ',') @> ARRAY['admin']
+    const containMatch = trimmed.match(/^string_to_array\s*\(\s*auth\.roles\(\)\s*,\s*','\s*\)\s*@>\s*ARRAY\s*\[(.+)\]$/i);
+    if (containMatch) {
+        const roles = containMatch[1].split(",").map(s => s.trim().replace(/^'|'$/g, ""));
+        return policy.rolesContain(roles);
+    }
+
+    // Handle OR
+    if (trimmed.toUpperCase().includes(" OR ")) {
+        const parts = trimmed.split(/ OR /i);
+        return policy.or(...parts.map(sqlToPolicy));
+    }
+
+    // Handle AND (very basic split, doesn't handle nested parens properly)
+    if (trimmed.toUpperCase().includes(" AND ")) {
+        const parts = trimmed.split(/ AND /i);
+        return policy.and(...parts.map(sqlToPolicy));
+    }
+
+    // Handle = and !=
+    const match = trimmed.match(/^(.+?)\s*(!?=)\s*(.+)$/);
+    if (match) {
+        const [, leftStr, op, rightStr] = match;
+        const left = parseOperand(leftStr.trim());
+        const right = parseOperand(rightStr.trim());
+        if (left && right) {
+            return policy.compare(left, op === "=" ? "eq" : "neq", right);
+        }
+    }
+
+    // Fallback to raw
+    return policy.raw(sql);
+}
+
+function parseOperand(str: string) {
+    // current_setting('app.user_id') or auth.uid()
+    if (/current_setting\s*\(\s*'app\.user_id'\s*\)/i.test(str) || /auth\.uid\(\)/i.test(str)) {
+        return policy.authUid();
+    }
+
+    // Literal string: 'value'
+    const stringMatch = str.match(/^'(.+)'$/);
+    if (stringMatch) {
+        return policy.literal(stringMatch[1]);
+    }
+
+    // Bare field name
+    if (/^\w+$/.test(str)) {
+        return policy.field(str);
+    }
+
+    return null;
+}

package/src/util/references.ts

@@ -1,6 +1,6 @@
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 
-export function getEntityImagePreviewPropertyKey<M extends Record<string, unknown>>(collection: EntityCollection<M>): string | undefined {
+export function getEntityImagePreviewPropertyKey<M extends Record<string, unknown>>(collection: CollectionConfig<M>): string | undefined {
 
     // find first storage property of type image
     for (const key in collection.properties) {
@@ -26,7 +26,7 @@ export function getEntityImagePreviewPropertyKey<M extends Record<string, unknow
     // and arrays of URL properties with image preview type
     for (const key in collection.properties) {
         const property = collection.properties[key];
-        if (property.type === "array" && property.of && !Array.isArray(property.of) && property.of.type === "string" && property.of.url === "image") {
+        if (property.type === "array" && property.of && !Array.isArray(property.of) && property.of.type === "string" && property.of.ui?.url === "image") {
             return key;
         }
     }

package/src/util/relations.ts

@@ -1,18 +1,18 @@
-import { CollectionWithRelations, EntityCollection, getDataSourceCapabilities, Property, Relation, RelationProperty } from "@rebasepro/types";
+import { CollectionConfig, getDataSourceCapabilities, Property, Relation, RelationProperty } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { generateForeignKeyName } from "@rebasepro/utils";
 
 export function sanitizeRelation(
     relation: Partial<Relation>,
-    sourceCollection: EntityCollection,
-    resolveCollection?: (slugOrTable: string) => EntityCollection | undefined
+    sourceCollection: CollectionConfig,
+    resolveCollection?: (slugOrTable: string) => CollectionConfig | undefined
 ): Relation {
     if (!relation.target) {
         throw new Error("Relation is missing a `target` collection.");
     }
 
     const rawTarget = relation.target;
-    let targetCollection: EntityCollection | undefined;
+    let targetCollection: CollectionConfig | undefined;
 
     if (typeof rawTarget === "string") {
         if (resolveCollection) {
@@ -20,7 +20,7 @@ export function sanitizeRelation(
         }
         if (!targetCollection) {
             targetCollection = { slug: rawTarget,
-name: rawTarget } as EntityCollection;
+name: rawTarget } as CollectionConfig;
         }
     } else if (typeof rawTarget === "function") {
         const evaluated = rawTarget();
@@ -30,13 +30,13 @@ name: rawTarget } as EntityCollection;
             }
             if (!targetCollection) {
                 targetCollection = { slug: evaluated,
-name: evaluated } as EntityCollection;
+name: evaluated } as CollectionConfig;
             }
         } else {
             targetCollection = evaluated;
         }
     } else if (rawTarget && typeof rawTarget === "object") {
-        targetCollection = rawTarget as EntityCollection;
+        targetCollection = rawTarget as CollectionConfig;
     }
 
     if (!targetCollection) {
@@ -89,7 +89,7 @@ name: evaluated } as EntityCollection;
 
                 try {
                     // Look for an owning relation on the target that points back to this collection
-                    const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? (((targetCollection as CollectionWithRelations).relations) || []) : [];
+                    const targetRelations = getDataSourceCapabilities(targetCollection.engine).supportsRelations ? (targetCollection.relations || []) : [];
                     for (const targetRel of targetRelations) {
                         if (targetRel.direction === "owning" &&
                             targetRel.cardinality === "one" &&
@@ -135,7 +135,7 @@ name: evaluated } as EntityCollection;
                     // `cardinality: "many" + direction: "owning"` is sufficient to identify owning M2M.
 
                     // 1. Check the explicit relations[] array
-                    const targetRelations = getDataSourceCapabilities(targetCollection.driver).supportsRelations ? (((targetCollection as CollectionWithRelations).relations) || []) : [];
+                    const targetRelations = getDataSourceCapabilities(targetCollection.engine).supportsRelations ? (targetCollection.relations || []) : [];
                     for (const targetRel of targetRelations) {
                         if (targetRel.cardinality === "many" &&
                             (targetRel.direction === "owning" || !targetRel.direction) &&
@@ -198,16 +198,15 @@ name: evaluated } as EntityCollection;
 }
 
 /** WeakMap cache — same collection instance always yields the same relation map. */
-const _resolvedRelationsCache = new WeakMap<EntityCollection, Record<string, Relation>>();
+const _resolvedRelationsCache = new WeakMap<CollectionConfig, Record<string, Relation>>();
 
 export function resolveCollectionRelations(
-    collection: EntityCollection
+    collection: CollectionConfig
 ): Record<string, Relation> {
     const cached = _resolvedRelationsCache.get(collection);
     if (cached) return cached;
 
-    if (!getDataSourceCapabilities(collection.driver).supportsRelations) return {};
-    const relCollection = collection as CollectionWithRelations;
+    if (!getDataSourceCapabilities(collection.engine).supportsRelations) return {};
     const relations: Record<string, Relation> = {};
 
     // Track which explicit relationName values have been registered so that
@@ -217,8 +216,8 @@ export function resolveCollectionRelations(
 
     // 1. Process explicit relations from the `relations` field.
     //    Each relation is stored once under its canonical relationName key.
-    if (relCollection.relations) {
-        relCollection.relations.forEach((relation: Relation) => {
+    if (collection.relations) {
+        collection.relations.forEach((relation: Relation) => {
             try {
                 const normalizedRelation = sanitizeRelation(relation, collection);
                 const relationKey = normalizedRelation.relationName;
@@ -252,7 +251,7 @@ export function resolveCollectionRelations(
 
                 // We previously skipped if the underlying relation was already registered under
                 // its canonical relationName in section 1. But we need to keep the property mapping
-                // for EntityFetchService to hydrate the relation back to the correct property key.
+                // for FetchService to hydrate the relation back to the correct property key.
                 // Deduplication for Drizzle schema generation is handled in generate-drizzle-schema-logic.ts.
 
                 if (!relation.relationName) {
@@ -276,7 +275,7 @@ export function resolvePropertyRelation({
 }: {
     propertyKey: string;
     property: Property;
-    sourceCollection: EntityCollection;
+    sourceCollection: CollectionConfig;
 }): Relation | undefined {
     if (property.type !== "relation") return undefined;
 
@@ -305,9 +304,9 @@ export function resolvePropertyRelation({
     return undefined;
 }
 
-export function getTableName(collection: EntityCollection): string {
-    if (getDataSourceCapabilities(collection.driver).supportsRelations) {
-        return (collection as CollectionWithRelations).table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
+export function getTableName(collection: CollectionConfig): string {
+    if (getDataSourceCapabilities(collection.engine).supportsRelations) {
+        return collection.table ?? toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
     }
     return toSnakeCase(collection.slug) ?? toSnakeCase(collection.name);
 }

package/src/util/resolutions.ts

@@ -1,9 +1,7 @@
 import {
     ArrayProperty,
     AuthController,
-    CollectionWithRelations,
-    CollectionWithSubcollections,
-    EntityCollection,
+    CollectionConfig,
     EnumValueConfig,
     EnumValues,
     NumberProperty,
@@ -12,7 +10,8 @@ import {
     Relation,
     RelationProperty,
     StringProperty,
-    getDataSourceCapabilities
+    getDataSourceCapabilities,
+    getDeclaredSubcollections
 } from "@rebasepro/types";
 
 type PropertyConfig = { property: unknown; [key: string]: unknown };
@@ -342,16 +341,17 @@ export function resolveEnumValues(input: EnumValues): EnumValueConfig[] | undefi
 }
 
 
-export function getSubcollections<M extends Record<string, unknown> = Record<string, unknown>>(collection: EntityCollection<M>): EntityCollection<Record<string, unknown>>[] {
+export function getSubcollections<M extends Record<string, unknown> = Record<string, unknown>>(collection: CollectionConfig<M>): CollectionConfig<Record<string, unknown>>[] {
     if (collection.childCollections) {
         return collection.childCollections() ?? [];
     }
 
-    if (getDataSourceCapabilities(collection.driver).supportsSubcollections && (collection as CollectionWithSubcollections).subcollections) {
-        return (collection as CollectionWithSubcollections).subcollections!() ?? [];
+    const declaredSubcollections = getDeclaredSubcollections(collection);
+    if (getDataSourceCapabilities(collection.engine).supportsSubcollections && declaredSubcollections) {
+        return declaredSubcollections() ?? [];
     }
 
-    if (getDataSourceCapabilities(collection.driver).supportsRelations) {
+    if (getDataSourceCapabilities(collection.engine).supportsRelations) {
         const resolvedRelations = resolveCollectionRelations(collection);
         const manyRelations = Object.values(resolvedRelations).filter((r: Relation) => r.cardinality === "many");
 
@@ -371,7 +371,7 @@ export function getSubcollections<M extends Record<string, unknown> = Record<str
                 }
             }
 
-            const baseOverrides: Partial<EntityCollection> = { slug: relationKey };
+            const baseOverrides: Partial<CollectionConfig> = { slug: relationKey };
             if (customName) {
                 baseOverrides.name = customName;
                 baseOverrides.singularName = customName;
@@ -379,8 +379,8 @@ export function getSubcollections<M extends Record<string, unknown> = Record<str
 
             const targetWithOverrides = { ...target,
 ...baseOverrides };
-            return (r.overrides ? mergeDeep(targetWithOverrides, r.overrides) : targetWithOverrides) as EntityCollection<Record<string, unknown>>;
-        }).filter((c: EntityCollection<Record<string, unknown>> | undefined): c is EntityCollection<Record<string, unknown>> => Boolean(c));
+            return (r.overrides ? mergeDeep(targetWithOverrides, r.overrides) : targetWithOverrides) as CollectionConfig<Record<string, unknown>>;
+        }).filter((c: CollectionConfig<Record<string, unknown>> | undefined): c is CollectionConfig<Record<string, unknown>> => Boolean(c));
     }
 
     return [];

package/src/util/storage.ts

@@ -1,6 +1,39 @@
-import { ArrayProperty, EntityValues, StorageConfig, StringProperty, UploadedFileContext } from "@rebasepro/types";
+import { ArrayProperty, EntityValues, StorageConfig, StorageSource, StorageSourceRegistry, StringProperty, UploadedFileContext } from "@rebasepro/types";
 import { randomString } from "@rebasepro/utils";
 
+/**
+ * Resolve the {@link StorageSource} to use for a property, given the key
+ * referenced by `StorageConfig.storageSource`.
+ *
+ * Resolution priority:
+ * 1. No `sourceKey` → the default source (backward compatible).
+ * 2. An explicit {@link StorageSourceRegistry} (e.g. `client.storageRegistry`).
+ * 3. A `sources` lookup map (e.g. the `StorageSourcesContext`).
+ * 4. Fall back to the default source.
+ *
+ * Shared by the upload hook, the markdown editor, and the read-only previews
+ * so the resolution logic lives in one place.
+ *
+ * @group Storage
+ */
+export function resolveStorageSource(params: {
+    /** Key from `StorageConfig.storageSource`. */
+    sourceKey?: string | null;
+    /** Built sources keyed by storage-source key (e.g. from context). */
+    sources?: Record<string, StorageSource>;
+    /** Optional explicit registry — takes precedence over `sources`. */
+    registry?: StorageSourceRegistry;
+    /** Default source, used when no key is set or the key cannot be resolved. */
+    defaultSource: StorageSource;
+}): StorageSource {
+    const { sourceKey, sources, registry, defaultSource } = params;
+    if (!sourceKey) return defaultSource;
+    if (registry) return registry.getOrDefault(sourceKey);
+    const fromSources = sources?.[sourceKey];
+    if (fromSources) return fromSources;
+    return defaultSource;
+}
+
 interface ResolveFilenameStringParams<M extends Record<string, unknown>> {
     input: string | ((context: UploadedFileContext) => (Promise<string> | string));
     storage: StorageConfig;