@rebasepro/types 0.7.0 → 0.9.0

package/dist/index.umd.js

@@ -2,9 +2,66 @@
 	typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global["Rebase Types"] = {}));
 })(this, function(exports) {
 	Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+	//#region src/errors.ts
+	/**
+	* The single error type thrown across the entire Rebase client surface —
+	* HTTP data/control-plane calls, realtime/WebSocket operations, and
+	* client-side logic errors (e.g. an unknown collection accessor). A `catch`
+	* block only ever needs to check for this one class:
+	*
+	* ```ts
+	* import { RebaseApiError } from "@rebasepro/client"; // re-exported
+	*
+	* try {
+	*   await client.data.products.update(id, { price: 9 });
+	* } catch (e) {
+	*   if (e instanceof RebaseApiError) {
+	*     if (e.status === 404) { ... }   // HTTP failures carry a status
+	*     console.error(e.code, e.details);
+	*   }
+	* }
+	* ```
+	*
+	* `status` is present for HTTP failures and `undefined` otherwise, so its
+	* presence distinguishes transport-level errors from realtime/logic errors.
+	*
+	* @group Errors
+	*/
+	var RebaseApiError = class extends Error {
+		/** HTTP status code, or `undefined` for non-HTTP errors. */
+		status;
+		/** Stable machine-readable error code, when the server supplied one. */
+		code;
+		/** Structured error payload from the server, when present. */
+		details;
+		constructor(message, init = {}) {
+			super(message);
+			this.name = "RebaseApiError";
+			this.status = init.status;
+			this.code = init.code;
+			this.details = init.details;
+			if (init.cause !== void 0) this.cause = init.cause;
+		}
+	};
+	/**
+	* Client-side logic error — raised before any request is made (e.g. accessing
+	* an unknown collection accessor when a typed dictionary is configured).
+	*
+	* A subclass of {@link RebaseApiError} (with no `status`), so a single
+	* `catch (e) { if (e instanceof RebaseApiError) ... }` handles it too.
+	*
+	* @group Errors
+	*/
+	var RebaseClientError = class extends RebaseApiError {
+		constructor(message) {
+			super(message);
+			this.name = "RebaseClientError";
+		}
+	};
+	//#endregion
 	//#region src/types/entities.ts
 	/**
-	* Class used to create a reference to an entity in a different path.
+	* Class used to create a reference to a entity in a different path.
 	*
 	* @example
 	* // Simple reference (most common case - single driver, single db)
@@ -38,7 +95,7 @@
 		*/
 		databaseId;
 		/**
-		* Create a reference to an entity.
+		* Create a reference to a entity.
 		*
 		* @example
 		* // Simple reference (most common case)
@@ -72,7 +129,7 @@
 		}
 	};
 	/**
-	* Class used to create a reference to an entity in a different path
+	* Class used to create a reference to a entity in a different path
 	*/
 	var EntityRelation = class {
 		__type = "relation";
@@ -126,30 +183,195 @@
 		}
 	};
 	//#endregion
+	//#region src/types/filter-operators.ts
+	/** Maps canonical operators to their REST short-code equivalents. */
+	var CANONICAL_TO_REST = {
+		"==": "eq",
+		"!=": "neq",
+		">": "gt",
+		">=": "gte",
+		"<": "lt",
+		"<=": "lte",
+		"in": "in",
+		"not-in": "nin",
+		"array-contains": "cs",
+		"array-contains-any": "csa",
+		"like": "like",
+		"ilike": "ilike",
+		"not-like": "nlike",
+		"not-ilike": "nilike",
+		"is-null": "isnull",
+		"is-not-null": "notnull"
+	};
+	/** Maps REST short-code operators to their canonical equivalents. */
+	var REST_TO_CANONICAL = {
+		"eq": "==",
+		"neq": "!=",
+		"gt": ">",
+		"gte": ">=",
+		"lt": "<",
+		"lte": "<=",
+		"in": "in",
+		"nin": "not-in",
+		"cs": "array-contains",
+		"csa": "array-contains-any",
+		"like": "like",
+		"ilike": "ilike",
+		"nlike": "not-like",
+		"nilike": "not-ilike",
+		"isnull": "is-null",
+		"notnull": "is-not-null"
+	};
+	/**
+	* Operators that test for null/not-null and therefore ignore their value.
+	* Codecs normalize the value of these conditions to `null`.
+	*/
+	var NULL_OPS = new Set(["is-null", "is-not-null"]);
+	/**
+	* Every canonical operator, in a stable order. Useful for engine capability
+	* declarations ({@link DataSourceCapabilities.filterOperators}) and for
+	* building operator subsets.
+	* @group Models
+	*/
+	var ALL_WHERE_FILTER_OPS = [
+		"<",
+		"<=",
+		"==",
+		"!=",
+		">=",
+		">",
+		"in",
+		"not-in",
+		"array-contains",
+		"array-contains-any",
+		"like",
+		"ilike",
+		"not-like",
+		"not-ilike",
+		"is-null",
+		"is-not-null"
+	];
+	/** All canonical operator strings for runtime validation. */
+	var CANONICAL_OPS = new Set(ALL_WHERE_FILTER_OPS);
+	/**
+	* Resolve any operator string (canonical or REST short-code) to its
+	* canonical `WhereFilterOp` form. Returns `undefined` for unknown operators.
+	*
+	* @example
+	* toCanonicalOp("==")   // "=="
+	* toCanonicalOp("eq")   // "=="
+	* toCanonicalOp("cs")   // "array-contains"
+	* toCanonicalOp("xyz")  // undefined
+	*/
+	function toCanonicalOp(op) {
+		if (CANONICAL_OPS.has(op)) return op;
+		return REST_TO_CANONICAL[op];
+	}
+	//#endregion
 	//#region src/types/collections.ts
 	/**
 	* Type guard for PostgreSQL collections.
-	* Returns true if the collection uses the Postgres driver (or the default driver).
+	* Returns true if the collection uses the Postgres engine (or the default engine).
 	* @group Models
 	*/
-	function isPostgresCollection(collection) {
-		return !collection.driver || collection.driver === "postgres";
+	function isPostgresCollectionConfig(collection) {
+		return !collection.engine || collection.engine === "postgres";
 	}
 	/**
 	* Type guard for Firebase / Firestore collections.
 	* @group Models
 	*/
-	function isFirebaseCollection(collection) {
-		return collection.driver === "firestore";
+	function isFirebaseCollectionConfig(collection) {
+		return collection.engine === "firestore";
 	}
 	/**
 	* Type guard for MongoDB collections.
 	* @group Models
 	*/
-	function isMongoDBCollection(collection) {
-		return collection.driver === "mongodb";
+	function isMongoDBCollectionConfig(collection) {
+		return collection.engine === "mongodb";
+	}
+	/**
+	* Returns the data path for a collection.
+	* For Firestore or MongoDB collections with a `path`, returns that value;
+	* otherwise falls back to `slug`.
+	*/
+	function getCollectionDataPath(collection) {
+		if (isFirebaseCollectionConfig(collection) && collection.path) return collection.path;
+		if (isMongoDBCollectionConfig(collection) && collection.path) return collection.path;
+		return collection.slug;
+	}
+	/**
+	* Reads a collection's driver-declared subcollections thunk (the `subcollections`
+	* field) independent of engine identity, so engine-agnostic code doesn't have to
+	* type-guard against a specific driver. Returns `undefined` when the collection
+	* declares none.
+	*
+	* Pair with `getDataSourceCapabilities(engine).supportsSubcollections` to decide
+	* whether the engine honours subcollections at all before reading them.
+	* @group Models
+	*/
+	function getDeclaredSubcollections(collection) {
+		return collection.subcollections;
 	}
 	//#endregion
+	//#region src/types/policy.ts
+	/** @group Models */
+	var policy = {
+		true: () => ({ kind: "true" }),
+		false: () => ({ kind: "false" }),
+		and: (...operands) => ({
+			kind: "and",
+			operands
+		}),
+		or: (...operands) => ({
+			kind: "or",
+			operands
+		}),
+		not: (operand) => ({
+			kind: "not",
+			operand
+		}),
+		compare: (left, op, right) => ({
+			kind: "compare",
+			op,
+			left,
+			right
+		}),
+		rolesOverlap: (roles) => ({
+			kind: "rolesOverlap",
+			roles
+		}),
+		rolesContain: (roles) => ({
+			kind: "rolesContain",
+			roles
+		}),
+		authenticated: () => ({ kind: "authenticated" }),
+		existsIn: (args) => ({
+			kind: "existsIn",
+			collection: args.collection,
+			where: args.where
+		}),
+		raw: (sql) => ({
+			kind: "raw",
+			sql
+		}),
+		field: (name) => ({
+			kind: "field",
+			name
+		}),
+		outerField: (name) => ({
+			kind: "outerField",
+			name
+		}),
+		literal: (value) => ({
+			kind: "literal",
+			value
+		}),
+		authUid: () => ({ kind: "authUid" }),
+		authRoles: () => ({ kind: "authRoles" })
+	};
+	//#endregion
 	//#region src/types/backend.ts
 	/**
 	* Type guard: does this admin support SQL operations?
@@ -198,6 +420,7 @@
 		supportsReferences: false,
 		supportsColumnTypes: true,
 		supportsRealtime: true,
+		filterOperators: ALL_WHERE_FILTER_OPS,
 		supportsSQLAdmin: true,
 		supportsDocumentAdmin: false,
 		supportsSchemaAdmin: true
@@ -212,6 +435,7 @@
 		supportsReferences: true,
 		supportsColumnTypes: false,
 		supportsRealtime: true,
+		filterOperators: ALL_WHERE_FILTER_OPS.filter((op) => op !== "like" && op !== "ilike" && op !== "not-like" && op !== "not-ilike"),
 		supportsSQLAdmin: false,
 		supportsDocumentAdmin: false,
 		supportsSchemaAdmin: false
@@ -226,6 +450,7 @@
 		supportsReferences: true,
 		supportsColumnTypes: false,
 		supportsRealtime: false,
+		filterOperators: ALL_WHERE_FILTER_OPS,
 		supportsSQLAdmin: false,
 		supportsDocumentAdmin: true,
 		supportsSchemaAdmin: true
@@ -244,6 +469,7 @@
 		supportsReferences: true,
 		supportsColumnTypes: true,
 		supportsRealtime: true,
+		filterOperators: ALL_WHERE_FILTER_OPS,
 		supportsSQLAdmin: true,
 		supportsDocumentAdmin: true,
 		supportsSchemaAdmin: true
@@ -255,13 +481,13 @@
 		"(default)": DEFAULT_CAPABILITIES
 	};
 	/**
-	* Look up capabilities for a given driver key.
-	* If `driver` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
+	* Look up capabilities for a given engine key.
+	* If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
 	* @group Models
 	*/
-	function getDataSourceCapabilities(driver) {
-		if (!driver) return POSTGRES_CAPABILITIES;
-		return CAPABILITIES_REGISTRY[driver] ?? DEFAULT_CAPABILITIES;
+	function getDataSourceCapabilities(engine) {
+		if (!engine) return POSTGRES_CAPABILITIES;
+		return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;
 	}
 	/**
 	* Register custom capabilities for a third-party driver.
@@ -271,6 +497,27 @@
 		CAPABILITIES_REGISTRY[capabilities.key] = capabilities;
 	}
 	//#endregion
+	//#region src/types/storage_source.ts
+	/**
+	* Describes a named storage backend — a place files live.
+	*
+	* Declared once and shared front + back: the frontend uses it to decide
+	* transport (HTTP proxy vs direct SDK), the backend uses the same `key`
+	* to resolve a StorageController, and collection properties reference
+	* a definition by its `key` via `StorageConfig.storageSource`.
+	*
+	* This mirrors the {@link DataSourceDefinition} pattern used for databases.
+	*
+	* @group Models
+	*/
+	/**
+	* The default storage source key, used when a property does not specify
+	* a `storageSource`. Shared by the frontend and backend registries so
+	* both agree on "the default storage backend".
+	* @group Models
+	*/
+	var DEFAULT_STORAGE_SOURCE_KEY = "(default)";
+	//#endregion
 	//#region src/types/component_ref.ts
 	/**
 	* Type guard: checks if a value is a `LazyComponentRef` produced by the
@@ -280,25 +527,65 @@
 		return typeof ref === "object" && ref !== null && "__rebaseLazy" in ref && ref.__rebaseLazy === true;
 	}
 	//#endregion
+	//#region src/controllers/storage.ts
+	/**
+	* Path prefix that marks an object as **public**. Files stored under this
+	* prefix are served without any auth token via a stable, permanent,
+	* CDN-cacheable URL (see {@link StorageSource.getSignedUrl}). Shared by the
+	* client SDK and the backend so both agree on which objects are public.
+	*
+	* @group Models
+	*/
+	var PUBLIC_STORAGE_PREFIX = "public/";
+	/**
+	* True when a storage key/path points at a public object (lives under
+	* {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the
+	* bucket* — strip any `bucket/` and `scheme://` prefixes first.
+	*
+	* @group Models
+	*/
+	function isPublicStoragePath(path) {
+		if (!path) return false;
+		let p = path;
+		const scheme = p.indexOf("://");
+		if (scheme !== -1) p = p.substring(scheme + 3);
+		p = p.replace(/^\/+/, "");
+		if (p.split("/").some((seg) => seg === "..")) return false;
+		return p.startsWith("public/") || p.startsWith(`default/public/`);
+	}
+	//#endregion
+	exports.ALL_WHERE_FILTER_OPS = ALL_WHERE_FILTER_OPS;
+	exports.CANONICAL_TO_REST = CANONICAL_TO_REST;
 	exports.DEFAULT_CAPABILITIES = DEFAULT_CAPABILITIES;
 	exports.DEFAULT_DATA_SOURCE_KEY = DEFAULT_DATA_SOURCE_KEY;
+	exports.DEFAULT_STORAGE_SOURCE_KEY = DEFAULT_STORAGE_SOURCE_KEY;
 	exports.EntityReference = EntityReference;
 	exports.EntityRelation = EntityRelation;
 	exports.FIREBASE_CAPABILITIES = FIREBASE_CAPABILITIES;
 	exports.GeoPoint = GeoPoint;
 	exports.MONGODB_CAPABILITIES = MONGODB_CAPABILITIES;
+	exports.NULL_OPS = NULL_OPS;
 	exports.POSTGRES_CAPABILITIES = POSTGRES_CAPABILITIES;
+	exports.PUBLIC_STORAGE_PREFIX = PUBLIC_STORAGE_PREFIX;
+	exports.REST_TO_CANONICAL = REST_TO_CANONICAL;
+	exports.RebaseApiError = RebaseApiError;
+	exports.RebaseClientError = RebaseClientError;
 	exports.Vector = Vector;
+	exports.getCollectionDataPath = getCollectionDataPath;
 	exports.getDataSourceCapabilities = getDataSourceCapabilities;
+	exports.getDeclaredSubcollections = getDeclaredSubcollections;
 	exports.isBranchAdmin = isBranchAdmin;
 	exports.isDocumentAdmin = isDocumentAdmin;
-	exports.isFirebaseCollection = isFirebaseCollection;
+	exports.isFirebaseCollectionConfig = isFirebaseCollectionConfig;
 	exports.isLazyComponentRef = isLazyComponentRef;
-	exports.isMongoDBCollection = isMongoDBCollection;
-	exports.isPostgresCollection = isPostgresCollection;
+	exports.isMongoDBCollectionConfig = isMongoDBCollectionConfig;
+	exports.isPostgresCollectionConfig = isPostgresCollectionConfig;
+	exports.isPublicStoragePath = isPublicStoragePath;
 	exports.isSQLAdmin = isSQLAdmin;
 	exports.isSchemaAdmin = isSchemaAdmin;
+	exports.policy = policy;
 	exports.registerDataSourceCapabilities = registerDataSourceCapabilities;
+	exports.toCanonicalOp = toCanonicalOp;
 });
 
 //# sourceMappingURL=index.umd.js.map