@rebasepro/types 0.10.0 → 0.10.1-canary.14e53ae

package/dist/controllers/client.d.ts

@@ -391,11 +391,13 @@ export interface RebaseServerClient<DB = unknown> extends RebaseClient<DB> {
     email: EmailService;
     /**
      * Execute raw SQL against the database. Always present server-side for SQL
-     * engines.
+     * engines. Values interpolated into the query should be passed via
+     * `params`, referenced as `$1`, `$2`, … placeholders in the query text.
      */
     sql(query: string, options?: {
         database?: string;
         role?: string;
+        params?: unknown[];
     }): Promise<Record<string, unknown>[]>;
 }
 /**

package/dist/controllers/data_driver.d.ts

@@ -32,6 +32,35 @@ export interface VectorSearchParams {
     /** Only return results within this distance threshold */
     threshold?: number;
 }
+/** Rows returned for a plain / text-search list read when the client sends no `limit`. */
+export declare const DEFAULT_LIST_LIMIT = 50;
+/** Rows returned for a vector-search list read when the client sends no `limit`. */
+export declare const DEFAULT_VECTOR_LIST_LIMIT = 10;
+/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+export declare const MAX_LIST_LIMIT = 1000;
+/** Overridable bounds for {@link resolveClientListLimit}. */
+export interface ListLimitBounds {
+    /** Default page size for plain and text-search reads. */
+    defaultLimit?: number;
+    /** Default page size for vector-search reads. */
+    vectorDefaultLimit?: number;
+    /** Upper bound clamped onto any client-supplied limit. */
+    maxLimit?: number;
+}
+/**
+ * Resolve a client-supplied list `limit` into a safe, always-defined value.
+ *
+ * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
+ *   so `0`, negatives, and absurd values can never bypass the cap.
+ * - An absent / blank / non-numeric limit falls back to the mode default:
+ *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+ *
+ * The return is never `undefined` — no ingress that routes its client limit
+ * through this can produce an unbounded read.
+ */
+export declare function resolveClientListLimit(rawLimit: number | string | null | undefined, opts?: ListLimitBounds & {
+    vectorSearch?: boolean;
+}): number;
 /**
  * @internal
  */

package/dist/index.es.js

@@ -416,6 +416,19 @@ function isBranchAdmin(admin) {
 	return !!admin && typeof admin.createBranch === "function";
 }
 //#endregion
+//#region src/types/channel_bus.ts
+/**
+* Whether `setting` is an already-constructed transport rather than a request
+* for a built-in one.
+*
+* Structural rather than nominal so that an instance from a *different copy* of
+* `@rebasepro/types` — an entirely normal outcome of a separately versioned
+* transport package — is still recognised.
+*/
+function isChannelBusInstance(setting) {
+	return typeof setting?.publish === "function";
+}
+//#endregion
 //#region src/types/data_source.ts
 /**
 * The default data-source key, used when a collection does not name a
@@ -541,6 +554,262 @@ function isLazyComponentRef(ref) {
 	return typeof ref === "object" && ref !== null && "__rebaseLazy" in ref && ref.__rebaseLazy === true;
 }
 //#endregion
+//#region src/types/project_manifest.ts
+/**
+* Version of the bundle *format* itself.
+*
+* Bumped only when the on-disk layout changes in a way an older runtime could
+* not read. A runtime accepts any bundle whose `bundleFormat` is less than or
+* equal to its own — old bundles keep booting on new runtimes, which is the
+* whole point of separating the artifact from the engine.
+*/
+var BUNDLE_FORMAT_VERSION = 1;
+/**
+* The runtime contract major.
+*
+* Distinct from the `@rebasepro/server` package version: the package may release
+* any number of minors and patches while this stays put. It changes only when
+* the bundle/runtime contract breaks compatibility, and a project's
+* `manifest.runtime` range is matched against *this*.
+*/
+var RUNTIME_CONTRACT_VERSION = 1;
+/** Header carrying the schema version an SDK was generated from. */
+var SCHEMA_VERSION_HEADER = "x-rebase-schema";
+//#endregion
+//#region src/types/collection_contract.ts
+function isSerializedCollectionRef(value) {
+	return typeof value === "object" && value !== null && typeof value.__collectionRef === "string";
+}
+/** Depth limit for the walk — deep enough for real configs, finite for cyclic ones. */
+var MAX_DEPTH = 64;
+/**
+* Resolve whatever a `target` thunk returns down to a collection.
+*
+* A target may be the collection, a module namespace (when the authoring file
+* used `import * as`), or a default-export wrapper. All three appear in real
+* projects, and the SDK generator already unwraps them the same way.
+*/
+function unwrapTarget(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const candidate = value;
+	if (candidate.default || candidate.__esModule) {
+		const inner = candidate.default;
+		if (inner && typeof inner === "object") return inner;
+	}
+	if (candidate.properties) return value;
+}
+/** The identity a serialized reference uses. Slug first — it is the routing key. */
+function refFor(collection) {
+	if (!collection) return void 0;
+	const withPath = collection;
+	return collection.slug || withPath.path || collection.name;
+}
+function toSerializable(value, seen, depth, state, key) {
+	if (depth > MAX_DEPTH) {
+		state.truncations++;
+		return;
+	}
+	if (typeof value === "function") {
+		if (key === "target") try {
+			const ref = refFor(unwrapTarget(value()));
+			return ref ? { __collectionRef: ref } : void 0;
+		} catch {
+			return;
+		}
+		return;
+	}
+	if (value === null || typeof value !== "object") return value;
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof RegExp) return value.source;
+	if (seen.has(value)) {
+		state.truncations++;
+		return;
+	}
+	const cached = state.memo.get(value);
+	if (cached !== void 0) return cached;
+	seen.add(value);
+	const truncationsBefore = state.truncations;
+	const memoize = (result) => {
+		if (result !== void 0 && state.truncations === truncationsBefore) state.memo.set(value, result);
+		return result;
+	};
+	try {
+		if (Array.isArray(value)) {
+			const items = value.map((item) => toSerializable(item, seen, depth + 1, state)).filter((item) => item !== void 0);
+			return memoize(value.length > 0 && items.length === 0 ? void 0 : items);
+		}
+		if ("$$typeof" in value) return void 0;
+		const entries = Object.entries(value);
+		const out = {};
+		for (const [k, v] of entries) {
+			const converted = toSerializable(v, seen, depth + 1, state, k);
+			if (converted !== void 0) out[k] = converted;
+		}
+		if (entries.length > 0 && Object.keys(out).length === 0) return void 0;
+		return memoize(out);
+	} finally {
+		seen.delete(value);
+	}
+}
+/**
+* Serialize collections for transport over the contract endpoint.
+*
+* Sorted by slug so the output — and therefore the schema hash computed from it
+* — does not depend on filesystem ordering.
+*/
+function serializeCollections(collections) {
+	return [...collections].sort((a, b) => String(a.slug ?? "").localeCompare(String(b.slug ?? ""))).map((collection) => toSerializable(collection, /* @__PURE__ */ new WeakSet(), 0, {
+		memo: /* @__PURE__ */ new WeakMap(),
+		truncations: 0
+	})).filter((c) => c !== void 0);
+}
+/**
+* Rebuild collections received from a contract endpoint.
+*
+* Relation refs become real thunks resolving through the returned set, so
+* downstream consumers — the SDK generator above all — see exactly the shape
+* they would have seen had the collections been imported from source.
+*
+* A ref naming a collection that is not in the payload resolves to `undefined`
+* rather than throwing: the generator already tolerates an unresolvable target
+* by falling back to a permissive key type, and a partial contract should still
+* produce a usable SDK.
+*/
+function deserializeCollections(payload) {
+	const collections = payload.filter((c) => typeof c === "object" && c !== null).map((c) => ({ ...c }));
+	const bySlug = /* @__PURE__ */ new Map();
+	for (const collection of collections) {
+		const ref = refFor(collection);
+		if (ref) bySlug.set(ref, collection);
+	}
+	const rehydrate = (value, depth) => {
+		if (depth > MAX_DEPTH || !value || typeof value !== "object") return;
+		if (Array.isArray(value)) {
+			for (const item of value) rehydrate(item, depth + 1);
+			return;
+		}
+		const record = value;
+		for (const [key, child] of Object.entries(record)) {
+			if (key === "target" && isSerializedCollectionRef(child)) {
+				const slug = child.__collectionRef;
+				record.target = () => bySlug.get(slug);
+				continue;
+			}
+			rehydrate(child, depth + 1);
+		}
+	};
+	for (const collection of collections) rehydrate(collection, 0);
+	return collections;
+}
+//#endregion
+//#region src/types/schema_version.ts
+/**
+* The schema version stamp.
+*
+* One function, used in three places that must agree or the whole drift-detection
+* story is noise: `rebase build` writes it into a bundle manifest, the runtime
+* serves it from the contract endpoint, and a generated SDK records the value it
+* was built from. If any two of those computed it differently, every client would
+* look permanently out of date.
+*
+* It covers **collections only** — the client's contract is the shape of the
+* data, so editing a hook or a server function must not invalidate every SDK in
+* every repository. That is a deliberate narrowing, not an oversight.
+*/
+/** Stable stringify: object keys sorted at every level, so key order cannot alter the hash. */
+function canonicalize(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+	return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
+}
+/**
+* Reduce a collection to the parts a generated client is actually built from.
+*
+* The version answers one question — "is this SDK stale?" — so it must change
+* exactly when the generated types could change, and never otherwise. Hashing a
+* whole collection fails both halves of that:
+*
+* - Security rules, callbacks, icons, groups and UI settings do not appear in a
+*   generated client, so including them reports perfectly current SDKs as stale.
+* - Worse, they are not stable *inputs*. The runtime applies default security
+*   rules when it loads collections, so the same source hashed before and after
+*   loading produced two different answers — a build-time stamp that could never
+*   match the server that served it.
+*
+* Codegen reads the slug (for the `Database` key and type names), the properties,
+* and the relations. That is the projection.
+*/
+function projectForCodegen(collection) {
+	const source = collection;
+	return {
+		slug: collection.slug ?? source.path,
+		properties: collection.properties,
+		relations: source.relations,
+		engine: source.engine,
+		dataSource: source.dataSource,
+		subcollections: source.subcollections?.map(projectForCodegen)
+	};
+}
+/**
+* Compute the canonical string a schema version hashes.
+*
+* Exposed separately so the hashing itself can differ by environment: Node has
+* `crypto`, and callers without it can still compare canonical forms directly.
+*/
+function canonicalSchemaPayload(collections) {
+	return canonicalize(serializeCollections(collections).map((collection) => projectForCodegen(collection)));
+}
+/**
+* A short, non-cryptographic digest of the canonical payload.
+*
+* FNV-1a style, 64 bits, as two 32-bit halves. This is an identity, not a
+* security boundary: nothing trusts a schema version to prove anything, it only
+* answers "is this the same schema as before". A hand-rolled hash keeps this
+* module free of `node:crypto`, so the identical function runs in the browser,
+* in the CLI, and in the runtime — which is the property that actually matters.
+*/
+function computeSchemaVersion(collections) {
+	const payload = canonicalSchemaPayload(collections);
+	let h1 = 2166136261;
+	let h2 = 16777619;
+	for (let i = 0; i < payload.length; i++) {
+		const code = payload.charCodeAt(i);
+		h1 ^= code;
+		h1 = h1 + ((h1 << 1) + (h1 << 4) + (h1 << 7) + (h1 << 8) + (h1 << 24)) >>> 0;
+		h2 ^= code + i;
+		h2 = h2 + ((h2 << 1) + (h2 << 5) + (h2 << 9) + (h2 << 15) + (h2 << 24)) >>> 0;
+	}
+	const hex = (n) => n.toString(16).padStart(8, "0");
+	return `v1:${hex(h1)}${hex(h2)}`;
+}
+//#endregion
+//#region src/controllers/data_driver.ts
+/** Rows returned for a plain / text-search list read when the client sends no `limit`. */
+var DEFAULT_LIST_LIMIT = 50;
+/** Rows returned for a vector-search list read when the client sends no `limit`. */
+var DEFAULT_VECTOR_LIST_LIMIT = 10;
+/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+var MAX_LIST_LIMIT = 1e3;
+/**
+* Resolve a client-supplied list `limit` into a safe, always-defined value.
+*
+* - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
+*   so `0`, negatives, and absurd values can never bypass the cap.
+* - An absent / blank / non-numeric limit falls back to the mode default:
+*   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+*
+* The return is never `undefined` — no ingress that routes its client limit
+* through this can produce an unbounded read.
+*/
+function resolveClientListLimit(rawLimit, opts = {}) {
+	const maxLimit = opts.maxLimit ?? 1e3;
+	if (rawLimit != null && String(rawLimit).trim() !== "") {
+		const parsed = typeof rawLimit === "number" ? rawLimit : parseInt(String(rawLimit), 10);
+		if (Number.isFinite(parsed)) return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
+	}
+	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
+}
+//#endregion
 //#region src/controllers/storage.ts
 /**
 * Path prefix that marks an object as **public**. Files stored under this
@@ -568,6 +837,6 @@ function isPublicStoragePath(path) {
 	return p.startsWith("public/") || p.startsWith(`default/public/`);
 }
 //#endregion
-export { ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_DATA_SOURCE_KEY, DEFAULT_STORAGE_SOURCE_KEY, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REST_TO_CANONICAL, RebaseApiError, RebaseClientError, Vector, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, isBranchAdmin, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isSQLAdmin, isSchemaAdmin, policy, registerDataSourceCapabilities, toCanonicalOp };
+export { ALL_WHERE_FILTER_OPS, ANONYMOUS_USER_ID, BUNDLE_FORMAT_VERSION, CANONICAL_TO_REST, DEFAULT_CAPABILITIES, DEFAULT_DATA_SOURCE_KEY, DEFAULT_LIST_LIMIT, DEFAULT_STORAGE_SOURCE_KEY, DEFAULT_VECTOR_LIST_LIMIT, EntityReference, EntityRelation, FIREBASE_CAPABILITIES, GeoPoint, MAX_LIST_LIMIT, MONGODB_CAPABILITIES, NULL_OPS, POSTGRES_CAPABILITIES, PUBLIC_STORAGE_PREFIX, REST_TO_CANONICAL, RUNTIME_CONTRACT_VERSION, RebaseApiError, RebaseClientError, SCHEMA_VERSION_HEADER, Vector, canonicalSchemaPayload, computeSchemaVersion, deserializeCollections, getCollectionDataPath, getDataSourceCapabilities, getDeclaredSubcollections, isBranchAdmin, isChannelBusInstance, isDocumentAdmin, isFirebaseCollectionConfig, isLazyComponentRef, isMongoDBCollectionConfig, isPostgresCollectionConfig, isPublicStoragePath, isSQLAdmin, isSchemaAdmin, isSerializedCollectionRef, policy, registerDataSourceCapabilities, resolveClientListLimit, serializeCollections, toCanonicalOp };
 
 //# sourceMappingURL=index.es.js.map