@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/storage/types.d.ts

@@ -53,8 +53,6 @@ export interface S3StorageConfig {
     maxFileSize?: number;
     /** Allowed MIME types (if not set, all types allowed) */
     allowedMimeTypes?: string[];
-    /** URL expiration time in seconds for signed URLs (default: 3600) */
-    signedUrlExpiration?: number;
 }
 /**
  * Google Cloud Storage configuration (works with GCS and Firebase Storage)
@@ -77,8 +75,6 @@ export interface GCSStorageConfig {
     maxFileSize?: number;
     /** Allowed MIME types */
     allowedMimeTypes?: string[];
-    /** Signed URL expiration in seconds (default: 3600) */
-    signedUrlExpiration?: number;
 }
 /**
  * Storage configuration — local filesystem, S3-compatible, or Google Cloud Storage.
@@ -96,16 +92,40 @@ export interface GCSStorageConfig {
 export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig | GCSStorageConfig;
 /** What a storage request is trying to do to an object. */
 export type { StorageOperation, StorageAuthorizeUser, StorageAuthorizeContext, StorageAuthorizeData, StorageAuthorize } from "@rebasepro/types";
+/**
+ * How the server writes an object. See {@link StorageController.putObject}.
+ */
+export interface PutObjectOptions {
+    /**
+     * Hold this write to the controller's upload limits: `maxFileSize` and
+     * `allowedMimeTypes`. Defaults to `true`.
+     *
+     * Those limits say what a user may upload. A write the server makes for
+     * itself, such as a database backup, passes `false`. A dump is neither of
+     * an allowed type nor, past a small database, under 50 MB. The upload
+     * routes never pass it.
+     */
+    uploadLimits?: boolean;
+}
 /**
  * Storage controller interface for backend implementations
  */
 export interface StorageController {
     /**
-     * Upload an object
+     * Upload an object.
+     *
+     * A write is held to the controller's upload limits — `maxFileSize` and
+     * `allowedMimeTypes` — unless `options.uploadLimits` is `false`. Only the
+     * server's own writes pass that; nothing a request sends reaches it.
      */
-    putObject(props: UploadFileProps): Promise<UploadFileResult>;
+    putObject(props: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
     /**
-     * Get a download URL (signed URL equivalent) for an object
+     * Get a download URL (signed URL equivalent) for an object.
+     *
+     * For server-side code only: no route hands this URL to a client. A
+     * client reads a private object through `/file/*` with the download
+     * token `GET /metadata/*` mints. The built-in S3 and GCS controllers sign
+     * it for an hour.
      */
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     /**
@@ -128,6 +148,29 @@ export interface StorageController {
      * Get object as a File
      */
     getObject(key: string, bucket?: string): Promise<File | null>;
+    /**
+     * Describe an object for serving it — its size, stored type and version —
+     * without reading its bytes, or `null` when there is no such object.
+     *
+     * Optional, together with {@link getObjectStream}. A controller that has
+     * both is served streamed: `GET /file/*` answers a `304`, a `416`, a `HEAD`
+     * and a cached image rendition from this alone, and otherwise reads only
+     * the bytes it sends — the requested range, a chunk at a time. One without
+     * them is served through {@link getObject}, which holds the whole object in
+     * memory for every request, a `Range` request for one megabyte included.
+     */
+    statObject?(key: string, bucket?: string): Promise<StoredObjectInfo | null>;
+    /**
+     * Read an object, or one byte range of it, as a stream, or `null` when
+     * there is no such object. See {@link statObject}.
+     *
+     * The stream holds a file or a connection until it is read to the end or
+     * cancelled, so a caller that decides not to read it must cancel it.
+     */
+    getObjectStream?(key: string, options?: {
+        bucket?: string;
+        range?: StoredObjectRange;
+    }): Promise<StoredObjectStream | null>;
     /**
      * Delete an object
      */
@@ -179,6 +222,38 @@ export interface StorageController {
      */
     maxFileSize?(): number;
 }
+/**
+ * What serving an object needs to know before deciding whether to read it.
+ * See {@link StorageController.statObject}.
+ */
+export interface StoredObjectInfo {
+    /** The whole object's size in bytes. */
+    size: number;
+    /** The stored content type — the uploader's claim, not a sniffed one. */
+    contentType: string;
+    /**
+     * The object's own modification time, in milliseconds since the epoch.
+     * The routes build `ETag`, `Last-Modified` and the transform cache key from
+     * it, so it must be the object's version, not the time of the read.
+     */
+    lastModified: number;
+}
+/** An inclusive byte range, as `Range: bytes=start-end` names one. */
+export interface StoredObjectRange {
+    start: number;
+    end: number;
+}
+/** An object's bytes as a stream. See {@link StorageController.getObjectStream}. */
+export interface StoredObjectStream extends StoredObjectInfo {
+    /** The bytes: the range when {@link range} is set, the whole object otherwise. */
+    stream: ReadableStream<Uint8Array>;
+    /**
+     * The range {@link stream} holds — the one asked for — or absent when it
+     * holds the whole object. A controller may answer a range with the whole
+     * object, as HTTP lets a server do; the caller then serves it whole.
+     */
+    range?: StoredObjectRange;
+}
 /**
  * Default maximum file size (50MB)
  */

package/dist/storage/upload-validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What every storage controller checks about a file before it stores it: the
+ * source's own size cap and, when configured, its allowed content types.
+ *
+ * One function for the three controllers, which carried a copy each. Both
+ * refusals are `ApiError`s, so they reach the caller as what they are. A plain
+ * `Error` was a 500 "Internal Server Error" on `/upload` and a 502 on TUS —
+ * after the client had sent every byte.
+ */
+export declare function validateUploadedFile(file: {
+    size: number;
+    type: string;
+}, maxSize: number, allowedMimeTypes: string[] | undefined): void;

package/dist/storage-resumable-VO-cMpse-C_YX71pO.js

@@ -0,0 +1,125 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+import "./resumable-upload-threshold-CKv-Ry0l.js";
+//#region ../common/src/util/resumable-upload.ts
+/** What `create` answers in `Rebase-Upload-Result` when the last `PATCH` will carry the stored object there. */
+var RESULT_ON_COMPLETE = "on-complete";
+var DEFAULT_RETRY_DELAYS_MS = [
+	250,
+	1e3,
+	3e3
+];
+/** `value` as UTF-8, base64-encoded — what `Upload-Metadata` carries. */
+function base64Utf8(value) {
+	const bytes = new TextEncoder().encode(value);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+/** Worth asking for the offset and sending again: an offset conflict, a lock, a rate limit, a server fault. */
+var isRetryable = (status) => status === 409 || status === 423 || status === 429 || status >= 500;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The stored object a finished upload reports, or `null` when the header says nothing readable. */
+function storedObjectOf(header) {
+	if (!header) return null;
+	let value;
+	try {
+		value = JSON.parse(decodeURIComponent(header));
+	} catch {
+		return null;
+	}
+	if (typeof value !== "object" || value === null) return null;
+	const key = "key" in value ? value.key : void 0;
+	const bucket = "bucket" in value ? value.bucket : void 0;
+	const storageUrl = "storageUrl" in value ? value.storageUrl : void 0;
+	if (typeof key !== "string" || typeof bucket !== "string" || typeof storageUrl !== "string") return null;
+	return {
+		key,
+		bucket,
+		storageUrl
+	};
+}
+/**
+* Upload `file` through a Rebase server's TUS endpoint, one chunk at a time.
+*
+* The server holds every upload to what `POST /storage/upload` holds a file
+* to — the source's and the property's limits, the authorize hook, the bucket
+* — and stores it with the same key, type and custom metadata, and fires the
+* same triggers. So a refusal is thrown as the multipart route would have
+* thrown it. A chunk that fails on the way — a dropped connection, a 5xx, a
+* conflict over the offset — is retried from the offset the server reports.
+*
+* Answers `unavailable` when the resumable path cannot carry this file and
+* the multipart one can: a server without the endpoint (or one too old to
+* report the stored object), an upload another instance cannot see (several
+* instances, no shared volume, no sticky sessions), or a chunk over the
+* server's body limit.
+*/
+async function uploadResumable(options) {
+	const { file, send } = options;
+	const chunkSize = Math.max(1, options.chunkSize ?? 8388608);
+	const retryDelays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+	const tus = { "Tus-Resumable": "1.0.0" };
+	const created = await send("POST", "", {
+		...tus,
+		"Upload-Length": String(file.size),
+		"Upload-Metadata": Object.entries(options.metadata).map(([name, value]) => `${name} ${base64Utf8(value)}`).join(",")
+	});
+	if (created.status === 404 || created.status === 405 || created.status === 501) return { unavailable: `the server has no resumable upload endpoint (${created.status})` };
+	if (created.status < 200 || created.status >= 300) throw created.error ?? /* @__PURE__ */ new Error(`The upload was refused (${created.status}).`);
+	const id = created.header("Location")?.split("?")[0].split("/").filter(Boolean).pop();
+	if (!id) return { unavailable: "the server did not say where the upload lives" };
+	const path = `/${encodeURIComponent(id)}`;
+	if (created.header("Rebase-Upload-Result") !== RESULT_ON_COMPLETE) {
+		await send("DELETE", path, tus).catch(() => void 0);
+		return { unavailable: "the server does not report the object a resumable upload stores" };
+	}
+	let offset = 0;
+	let lastFailure;
+	for (let attempt = 0;;) {
+		const end = Math.min(file.size, offset + chunkSize);
+		let response;
+		try {
+			response = await send("PATCH", path, {
+				...tus,
+				"Upload-Offset": String(offset),
+				"Content-Type": "application/offset+octet-stream"
+			}, file.slice(offset, end));
+		} catch (error) {
+			lastFailure = error instanceof Error ? error : new Error(String(error));
+		}
+		if (response && response.status >= 200 && response.status < 300) {
+			attempt = 0;
+			const reported = Number(response.header("Upload-Offset"));
+			offset = Number.isFinite(reported) && reported > offset ? reported : end;
+			if (offset < file.size) continue;
+			const stored = storedObjectOf(response.header("Rebase-Upload-Result"));
+			if (!stored) throw new Error("The upload finished, but the server did not say where it stored it.");
+			return { stored };
+		}
+		if (response?.status === 404) return { unavailable: "the server no longer knows this upload — another instance may have answered" };
+		if (response?.status === 413) {
+			await send("DELETE", path, tus).catch(() => void 0);
+			return { unavailable: "a chunk is over the server's request body limit" };
+		}
+		if (response && !isRetryable(response.status)) {
+			await send("DELETE", path, tus).catch(() => void 0);
+			throw response.error ?? /* @__PURE__ */ new Error(`The upload was refused (${response.status}).`);
+		}
+		if (response) lastFailure = response.error ?? /* @__PURE__ */ new Error(`The upload failed (${response.status}).`);
+		if (attempt >= retryDelays.length) throw lastFailure ?? /* @__PURE__ */ new Error("The upload failed.");
+		await sleep(retryDelays[attempt++]);
+		try {
+			const progress = await send("HEAD", path, tus);
+			if (progress.status === 404) return { unavailable: "the server no longer knows this upload — another instance may have answered" };
+			const held = Number(progress.header("Upload-Offset"));
+			if (progress.status >= 200 && progress.status < 300 && Number.isFinite(held)) offset = held;
+		} catch {}
+	}
+}
+//#endregion
+export { uploadResumable };
+
+//# sourceMappingURL=storage-resumable-VO-cMpse-C_YX71pO.js.map

package/dist/storage-resumable-VO-cMpse-C_YX71pO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-resumable-VO-cMpse-C_YX71pO.js","names":[],"sources":["../../common/src/util/resumable-upload.ts"],"sourcesContent":["import type { UploadFileResult } from \"@rebasepro/types\";\nimport { RESUMABLE_UPLOAD_THRESHOLD } from \"./resumable-upload-threshold\";\n\n/** One response, as the resumable upload reads it. */\nexport interface ResumableUploadResponse {\n    status: number;\n    header(name: string): string | null;\n    /** The error a non-2xx response stands for, as the transport reports it. */\n    error?: Error;\n}\n\n/**\n * Send one TUS request. `path` is `\"\"` for the creation request and\n * `/<upload id>` after it, relative to the source's `…/storage/tus` endpoint.\n * Answers every HTTP status; throws only when no response arrived.\n */\nexport type ResumableUploadSend = (\n    method: \"POST\" | \"PATCH\" | \"HEAD\" | \"DELETE\",\n    path: string,\n    headers: Record<string, string>,\n    body?: Blob\n) => Promise<ResumableUploadResponse>;\n\nexport interface ResumableUploadOptions {\n    file: Blob;\n    /** `Upload-Metadata` entries: `key`, `filename`, `filetype`, `bucket`, `storageId`, `collection`, `property`, `metadata_<name>`. */\n    metadata: Record<string, string>;\n    send: ResumableUploadSend;\n    /** Bytes per `PATCH`. Default {@link RESUMABLE_UPLOAD_THRESHOLD}. */\n    chunkSize?: number;\n    /** How long to wait before each retry of a chunk; its length is the number of retries. */\n    retryDelaysMs?: readonly number[];\n}\n\n/**\n * What a resumable upload came to: the stored object, or — for a reason the\n * multipart route does not share — nothing, and the caller sends the file\n * through `POST /storage/upload` instead.\n */\nexport type ResumableUploadOutcome =\n    | { stored: UploadFileResult }\n    | { unavailable: string };\n\n/** What `create` answers in `Rebase-Upload-Result` when the last `PATCH` will carry the stored object there. */\nconst RESULT_ON_COMPLETE = \"on-complete\";\nconst DEFAULT_RETRY_DELAYS_MS = [250, 1_000, 3_000];\n\n/** `value` as UTF-8, base64-encoded — what `Upload-Metadata` carries. */\nfunction base64Utf8(value: string): string {\n    const bytes = new TextEncoder().encode(value);\n    let binary = \"\";\n    for (const byte of bytes) binary += String.fromCharCode(byte);\n    return btoa(binary);\n}\n\n/** Worth asking for the offset and sending again: an offset conflict, a lock, a rate limit, a server fault. */\nconst isRetryable = (status: number) => status === 409 || status === 423 || status === 429 || status >= 500;\n\nconst sleep = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms));\n\n/** The stored object a finished upload reports, or `null` when the header says nothing readable. */\nfunction storedObjectOf(header: string | null): UploadFileResult | null {\n    if (!header) return null;\n    let value: unknown;\n    try {\n        value = JSON.parse(decodeURIComponent(header));\n    } catch {\n        return null;\n    }\n    if (typeof value !== \"object\" || value === null) return null;\n    const key = \"key\" in value ? value.key : undefined;\n    const bucket = \"bucket\" in value ? value.bucket : undefined;\n    const storageUrl = \"storageUrl\" in value ? value.storageUrl : undefined;\n    if (typeof key !== \"string\" || typeof bucket !== \"string\" || typeof storageUrl !== \"string\") return null;\n    return { key, bucket, storageUrl };\n}\n\n/**\n * Upload `file` through a Rebase server's TUS endpoint, one chunk at a time.\n *\n * The server holds every upload to what `POST /storage/upload` holds a file\n * to — the source's and the property's limits, the authorize hook, the bucket\n * — and stores it with the same key, type and custom metadata, and fires the\n * same triggers. So a refusal is thrown as the multipart route would have\n * thrown it. A chunk that fails on the way — a dropped connection, a 5xx, a\n * conflict over the offset — is retried from the offset the server reports.\n *\n * Answers `unavailable` when the resumable path cannot carry this file and\n * the multipart one can: a server without the endpoint (or one too old to\n * report the stored object), an upload another instance cannot see (several\n * instances, no shared volume, no sticky sessions), or a chunk over the\n * server's body limit.\n */\nexport async function uploadResumable(options: ResumableUploadOptions): Promise<ResumableUploadOutcome> {\n    const { file, send } = options;\n    const chunkSize = Math.max(1, options.chunkSize ?? RESUMABLE_UPLOAD_THRESHOLD);\n    const retryDelays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;\n    const tus = { \"Tus-Resumable\": \"1.0.0\" };\n\n    const created = await send(\"POST\", \"\", {\n        ...tus,\n        \"Upload-Length\": String(file.size),\n        \"Upload-Metadata\": Object.entries(options.metadata)\n            .map(([name, value]) => `${name} ${base64Utf8(value)}`)\n            .join(\",\")\n    });\n    if (created.status === 404 || created.status === 405 || created.status === 501) {\n        return { unavailable: `the server has no resumable upload endpoint (${created.status})` };\n    }\n    if (created.status < 200 || created.status >= 300) {\n        throw created.error ?? new Error(`The upload was refused (${created.status}).`);\n    }\n    const id = created.header(\"Location\")?.split(\"?\")[0].split(\"/\").filter(Boolean).pop();\n    if (!id) return { unavailable: \"the server did not say where the upload lives\" };\n    const path = `/${encodeURIComponent(id)}`;\n    if (created.header(\"Rebase-Upload-Result\") !== RESULT_ON_COMPLETE) {\n        await send(\"DELETE\", path, tus).catch(() => undefined);\n        return { unavailable: \"the server does not report the object a resumable upload stores\" };\n    }\n\n    let offset = 0;\n    let lastFailure: Error | undefined;\n    for (let attempt = 0; ;) {\n        const end = Math.min(file.size, offset + chunkSize);\n        let response: ResumableUploadResponse | undefined;\n        try {\n            response = await send(\"PATCH\", path, {\n                ...tus,\n                \"Upload-Offset\": String(offset),\n                \"Content-Type\": \"application/offset+octet-stream\"\n            }, file.slice(offset, end));\n        } catch (error: unknown) {\n            // No response: the connection dropped. Ask where the upload got to.\n            lastFailure = error instanceof Error ? error : new Error(String(error));\n        }\n\n        if (response && response.status >= 200 && response.status < 300) {\n            attempt = 0;\n            const reported = Number(response.header(\"Upload-Offset\"));\n            offset = Number.isFinite(reported) && reported > offset ? reported : end;\n            if (offset < file.size) continue;\n            const stored = storedObjectOf(response.header(\"Rebase-Upload-Result\"));\n            if (!stored) throw new Error(\"The upload finished, but the server did not say where it stored it.\");\n            return { stored };\n        }\n        if (response?.status === 404) {\n            return { unavailable: \"the server no longer knows this upload — another instance may have answered\" };\n        }\n        if (response?.status === 413) {\n            await send(\"DELETE\", path, tus).catch(() => undefined);\n            return { unavailable: \"a chunk is over the server's request body limit\" };\n        }\n        if (response && !isRetryable(response.status)) {\n            await send(\"DELETE\", path, tus).catch(() => undefined);\n            throw response.error ?? new Error(`The upload was refused (${response.status}).`);\n        }\n        if (response) lastFailure = response.error ?? new Error(`The upload failed (${response.status}).`);\n\n        if (attempt >= retryDelays.length) throw lastFailure ?? new Error(\"The upload failed.\");\n        await sleep(retryDelays[attempt++]);\n        // Resume from what the server holds, which may be more than was\n        // acknowledged (the chunk arrived, its answer did not) or less.\n        try {\n            const progress = await send(\"HEAD\", path, tus);\n            if (progress.status === 404) {\n                return { unavailable: \"the server no longer knows this upload — another instance may have answered\" };\n            }\n            const held = Number(progress.header(\"Upload-Offset\"));\n            if (progress.status >= 200 && progress.status < 300 && Number.isFinite(held)) offset = held;\n        } catch {\n            // Still no connection: the next attempt asks again.\n        }\n    }\n}\n"],"mappings":"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"}

package/dist/strings.es-BeZWAodn.js

@@ -0,0 +1,256 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+//#region ../types/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. See {@link RebaseErrorCode}. */
+	code;
+	/** Structured error payload from the server, when present. */
+	details;
+	/** See {@link RebaseErrorInit.requestId}. Quote it in a bug report. */
+	requestId;
+	/** See {@link RebaseErrorInit.retryAfterSeconds}. */
+	retryAfterSeconds;
+	constructor(message, init = {}) {
+		super(message);
+		this.name = "RebaseApiError";
+		this.status = init.status;
+		this.code = init.code;
+		this.details = init.details;
+		this.requestId = init.requestId;
+		this.retryAfterSeconds = init.retryAfterSeconds;
+		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 {
+	/**
+	* `init` is the same one {@link RebaseApiError} takes, and it is what makes
+	* `code` reachable at all.
+	*
+	* The constructor used to accept a message and nothing else, so every
+	* client-side failure — an undefined filter value, an unknown accessor,
+	* `listen()` on a client built with `realtime: false`, a function name with
+	* a `/` in it, `refreshSession()` while signed out — arrived with `code ===
+	* undefined`. The documented `switch (e.code)` in this file's own example
+	* fell to `default: throw e` for all of them, and the only client-side error
+	* that *did* carry a code was `OFFLINE`, because that one path minted a
+	* `RebaseApiError` instead.
+	*/
+	constructor(message, init = {}) {
+		super(message, init);
+		this.name = "RebaseClientError";
+	}
+};
+/**
+* Brand for a contract method a particular client cannot serve.
+*
+* `Symbol.for` rather than a fresh symbol: two copies of `@rebasepro/types` in
+* one tree — which happens, see `docs/dependency-duplication-traps.md` — must
+* agree about it, and a module-local symbol would not.
+*/
+var UNSUPPORTED_METHOD = Symbol.for("rebase.unsupportedMethod");
+function unsupportedMethod(message) {
+	const stub = () => {
+		throw new RebaseClientError(message, { code: "REALTIME_DISABLED" });
+	};
+	stub[UNSUPPORTED_METHOD] = true;
+	return stub;
+}
+/**
+* Can this method actually do anything?
+*
+* `true` for a stub from {@link unsupportedMethod} **and** for a method that is
+* simply not there — a partial client, a hand-built test double, an
+* implementation written against an older shape of the interface. Both mean the
+* same thing to a caller, so both answer the same way, and an adapter that
+* checks this cannot be caught out by either.
+*
+* Ordinary code does not need it: calling the method and letting it throw is
+* the normal path. Adapters do — the admin panel chooses between subscribing
+* and a one-shot `find()` by asking whether the client can listen, and a UI
+* that subscribes into a throw is worse than one that polls. This is the
+* question `if (accessor.listen)` used to be asking, made explicit now that the
+* method is always there to call.
+*
+* @group Errors
+*/
+function isUnsupported(method) {
+	if (typeof method !== "function") return true;
+	return method[UNSUPPORTED_METHOD] === true;
+}
+/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
+var MAX_LIST_LIMIT = 1e3;
+/**
+* Thrown by {@link resolveClientListLimit} for a `limit` the platform will not
+* serve. Carries an HTTP status so an ingress that speaks HTTP can forward it
+* verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.
+*
+* @group Errors
+*/
+var ListLimitError = class ListLimitError extends RebaseApiError {
+	/** The ceiling that was exceeded — what the caller should page by instead. */
+	maxLimit;
+	constructor(message, maxLimit) {
+		super(message, {
+			status: 400,
+			code: "INVALID_LIMIT"
+		});
+		this.name = "ListLimitError";
+		this.maxLimit = maxLimit;
+		Object.setPrototypeOf(this, ListLimitError.prototype);
+	}
+};
+/**
+* Resolve a client-supplied list `limit` into a safe, always-defined value.
+*
+* - An absent / blank limit falls back to the mode default:
+*   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+* - A limit that is present must be an integer in `[1, maxLimit]`. Anything
+*   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws
+*   {@link ListLimitError} rather than being coerced into range, because every
+*   coercion answers a question the caller did not ask with a page it cannot
+*   tell apart from the whole collection.
+*
+* The return is never `undefined` — no ingress that routes its client limit
+* through this can produce an unbounded read.
+*
+* @throws {ListLimitError} when a present `limit` is not an integer in range.
+*/
+function resolveClientListLimit(rawLimit, opts = {}) {
+	const maxLimit = opts.maxLimit ?? 1e3;
+	if (rawLimit != null && String(rawLimit).trim() !== "") {
+		const parsed = typeof rawLimit === "number" ? rawLimit : Number(String(rawLimit).trim());
+		if (!Number.isInteger(parsed) || parsed < 1) throw new ListLimitError(`Invalid \`limit\`: ${String(rawLimit)}. Expected a whole number between 1 and ${maxLimit}.`, maxLimit);
+		if (parsed > maxLimit) throw new ListLimitError(`\`limit\` ${parsed} is above the maximum of ${maxLimit}. Ask for at most ${maxLimit} rows per read and page through the rest with \`offset\` — answering with a smaller page would be indistinguishable from there being no more rows.`, maxLimit);
+		return parsed;
+	}
+	return opts.vectorSearch ? opts.vectorDefaultLimit ?? 10 : opts.defaultLimit ?? 50;
+}
+var snakeCaseRegex = /[A-Z]{2,}(?=[A-Z][a-z]|\b)|[A-Z]?[a-z]+|[0-9]+(?:[a-z](?![a-z]))?|[A-Z]/g;
+var toSnakeCase = (str) => {
+	if (!str || typeof str !== "string") return "";
+	const regExpMatchArray = str.match(snakeCaseRegex);
+	if (!regExpMatchArray) return "";
+	return regExpMatchArray.map((x) => x.toLowerCase()).join("_");
+};
+/**
+* Are these two identifiers one edit apart, ignoring case?
+*
+* Tight on purpose. A suggester that fires on two edits offers `columnWidth`
+* for `colWith` and `readOnly` for `required`, and a "did you mean" that is
+* usually wrong teaches people to stop reading them. One edit covers what
+* actually happens — a dropped letter (`multilne`), a doubled one, a transposed
+* pair (`validaton`), a wrong case — and nothing else.
+*
+* Lives here rather than beside either caller because both the CLI's manifest
+* reader and the server's collection validator answer the same question about
+* an unknown key, and two copies of a similarity rule is two rules the moment
+* one of them is tuned.
+*/
+function isNearMiss(a, b) {
+	const x = a.toLowerCase();
+	const y = b.toLowerCase();
+	if (x === y) return true;
+	if (Math.abs(x.length - y.length) > 1) return false;
+	const [shorter, longer] = x.length <= y.length ? [x, y] : [y, x];
+	let i = 0;
+	let j = 0;
+	let edits = 0;
+	while (i < shorter.length && j < longer.length) {
+		if (shorter[i] === longer[j]) {
+			i++;
+			j++;
+			continue;
+		}
+		if (++edits > 1) return false;
+		if (shorter.length === longer.length) i++;
+		j++;
+	}
+	return edits + (longer.length - j) + (shorter.length - i) <= 1;
+}
+/**
+* The key in `known` that `key` was probably meant to be, if any.
+*
+* `undefined` when nothing is close — which is the common case for a key that
+* is simply from a newer version, and the reason the caller must be able to say
+* "unknown" without saying "wrong".
+*/
+function suggestNearMiss(known, key) {
+	return known.find((candidate) => isNearMiss(candidate, key));
+}
+/**
+* The terms a user meant when they typed into a search box.
+*
+* A search box is not a substring box. Typing `sebastian melendez` on a
+* collection whose name is split across `first_name` and `last_name` has to
+* find the row, and matching the whole string against each field separately
+* cannot: no single column holds both words. Splitting on whitespace and
+* requiring *every* term to match *some* field is what does, and it is what
+* `websearch_to_tsquery` already does for collections that declared a `search`
+* block — so this is also what keeps the two search paths answering the same
+* question.
+*
+* It fixes the trailing space too: `sebastian ` matched nothing at all, because
+* the space was part of the pattern.
+*
+* A double-quoted run is one term, again matching the full-text path, so a
+* caller who really does want the phrase can ask for it. An unbalanced quote is
+* stripped rather than honoured — the alternative is that everything after a
+* stray `"` silently becomes one long term that matches nothing.
+*
+* Returns an empty array for a string with no terms in it at all (whitespace,
+* or nothing but quotes); the caller decides what an empty search means, since
+* only it knows whether "no constraint" or "no rows" is the safe reading.
+*/
+function splitSearchTerms(searchString, maxTerms = 8) {
+	const terms = [];
+	const pattern = /"([^"]*)"|(\S+)/g;
+	let match;
+	while ((match = pattern.exec(searchString)) !== null) {
+		const term = (match[1] ?? match[2].replace(/"/g, "")).trim();
+		if (!term) continue;
+		terms.push(term);
+		if (terms.length >= maxTerms) break;
+	}
+	return terms;
+}
+//#endregion
+export { MAX_LIST_LIMIT as a, RebaseClientError as c, ListLimitError as i, isUnsupported as l, suggestNearMiss as n, resolveClientListLimit as o, toSnakeCase as r, RebaseApiError as s, splitSearchTerms as t, unsupportedMethod as u };
+
+//# sourceMappingURL=strings.es-BeZWAodn.js.map