@rebasepro/server 0.25.0 → 0.26.0

package/dist/storage/GCSStorageController.d.ts

@@ -24,6 +24,8 @@ export declare class GCSStorageController implements StorageController {
      * @see S3StorageController.knownBuckets
      */
     knownBuckets(): string[];
+    /** See {@link StorageController.storageLocation}: bucket names are global. */
+    storageLocation(): string;
     putObject({ file, key, metadata, bucket }: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
     /**
      * Read the object's metadata and nothing else — no signing.

package/dist/storage/LocalStorageController.d.ts

@@ -67,6 +67,11 @@ export declare class LocalStorageController implements StorageController {
      * not have been written to yet.
      */
     knownBuckets(): string[];
+    /**
+     * See {@link StorageController.storageLocation}: the default bucket's
+     * directory, with the storage root's links resolved.
+     */
+    storageLocation(): string;
     /**
      * Ensure directory exists, creating it if necessary
      */
@@ -128,11 +133,11 @@ export declare class LocalStorageController implements StorageController {
     /**
      * A folder's entries for a listing page.
      *
-     * A page token is an index into these entries, and every continuation
-     * page used to read the whole folder again to find its place: a folder of
+     * A page token names the last of these entries a page read, and every
+     * continuation page used to read the whole folder again to find its place: a folder of
      * n entries listed in pages of p cost n/p full reads. A first page reads
      * the folder and, when there is a next page, keeps the read; a
-     * continuation page indexes into it while all of these hold:
+     * continuation page finds its place in it while all of these hold:
      *
      *  - the folder's mtime is the one read with it. Adding, removing or
      *    renaming an entry changes it, which is the invalidation;

package/dist/storage/S3StorageController.d.ts

@@ -24,6 +24,8 @@ export declare class S3StorageController implements StorageController {
      * can reach — and a mistyped one came back as "file not found".
      */
     knownBuckets(): string[];
+    /** See {@link StorageController.storageLocation}: the endpoint (AWS when none) and the bucket. */
+    storageLocation(): string;
     /** See {@link StorageController.maxFileSize}. */
     maxFileSize(): number;
     /**

package/dist/storage/maintenance-keys.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where storage maintenance keeps its own records inside a source: the state
+ * and result of an orphan scan (`rebase storage orphans`), which a worker
+ * writes and any server process reads back.
+ *
+ * Reserved at the route layer like the rendition space, in both directions. A
+ * scan's result is the list a later delete acts on, so a caller who could
+ * write one could name files for an administrator's delete to remove; and it
+ * lists keys a caller may not be allowed to see.
+ */
+export declare const MAINTENANCE_PREFIX = "_rebase/maintenance/";
+/**
+ * True for a key in the reserved maintenance space — the prefix itself, or
+ * anything under it. Folded the way the filesystem under a local bucket folds
+ * it, as {@link isRenditionKey} is.
+ */
+export declare function isMaintenanceKey(key: string): boolean;

package/dist/storage/maintenance-routes.d.ts

@@ -1,23 +1,46 @@
 /**
  * `/admin/storage` — the routes behind `rebase storage orphans` and
  * `rebase storage move`. Admin-only; the caller mounts them behind the admin
- * gate (`database:read` to read, `database:write` to delete or move).
+ * gate (`database:read` to read, `database:write` for every other method).
  *
- *   GET    /orphans?storageId=&olderThanHours=   objects no row names
- *   DELETE /orphans?storageId=&olderThanHours=   delete them, found again first
+ *   POST   /orphans/scans?storageId=&olderThanHours=   start a scan, in the background
+ *   GET    /orphans/scans/:id?storageId=               its progress, then its report
+ *   DELETE /orphans?scan=:id&storageId=                delete a completed scan's orphans, in the background
+ *   GET    /orphans?storageId=&olderThanHours=         deprecated: a scan inside the request
+ *   DELETE /orphans?storageId=&olderThanHours=         deprecated: scan and delete inside the request
  *   POST   /move  { from, to, prefix?, cursor?, limit?, deleteSource? }
+ *   POST   /move/verify  (the same body)            what a move left behind
  */
 import { Hono } from "hono";
-import type { CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { CollectionCallbacks, CollectionConfig, DataDriver } from "@rebasepro/types";
 import type { HonoEnv } from "../api/types.js";
+import type { JobQueueClient } from "../jobs/types.js";
 import type { StorageController } from "./types.js";
 import type { StorageRegistry } from "./storage-registry.js";
+import { type OrphanScanService } from "./orphan-scans.js";
 export interface StorageMaintenanceRoutesConfig {
     registry?: StorageRegistry;
     controller?: StorageController;
     /** The collections whose rows are read for references, read per request. */
     collections: () => readonly CollectionConfig[];
-    /** The unscoped driver serving a collection: every row, whoever wrote it. */
+    /**
+     * The unscoped driver serving a collection: every row, whoever wrote it.
+     * Its `scanStoredRows` is read when it has one — rows as stored, past
+     * every read hook.
+     */
     driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+    /** The global callbacks, read per request: a global read hook makes every collection hooked. */
+    globalCallbacks?: () => CollectionCallbacks | undefined;
+    /** Row history, when kept: a file only an entry names is restored by a revert. */
+    history?: {
+        scanStoredValues?(pageSize?: number): AsyncIterable<unknown[]>;
+    };
+    /** The durable job queue a scan runs on, read per scan. Absent: scans run in this process. */
+    jobs?: () => JobQueueClient | undefined;
+    /**
+     * The scan service, when the backend shares one with the job queue's
+     * `storage.orphans` handler. Built from the fields above when left out.
+     */
+    orphanScans?: OrphanScanService;
 }
 export declare function createStorageMaintenanceRoutes(config: StorageMaintenanceRoutesConfig): Hono<HonoEnv>;

package/dist/storage/maintenance.d.ts

@@ -11,7 +11,7 @@
  * whichever property holds it. A file is reported only when nothing points at
  * it at all.
  */
-import type { CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { CollectionCallbacks, CollectionConfig, DataDriver } from "@rebasepro/types";
 import type { StorageController } from "./types.js";
 /** One stored object, as a listing describes it. */
 export interface StoredObjectEntry {
@@ -51,6 +51,12 @@ export interface UnscannedCollection {
     collection: string;
     reason: string;
 }
+/**
+ * Whether reading a collection through `fetchCollection` could hide a row or
+ * change a value: a `beforeQuery` or an `afterRead`, the collection's own, a
+ * global one, or a property's.
+ */
+export declare function hasReadHooks(collection: CollectionConfig, globalCallbacks?: CollectionCallbacks): boolean;
 /**
  * Remove from `keys` every key some row names.
  *
@@ -59,13 +65,28 @@ export interface UnscannedCollection {
  * serves the collection. What is left in `keys` afterwards is named by no row.
  * A collection that could not be read is returned, and its rows count for
  * nothing: a caller must not treat what is left as unused when any is.
+ *
+ * Rows are read as stored, through the driver's `scanStoredRows`. A driver
+ * without it is read through `fetchCollection` only for a collection with no
+ * read hooks: a `beforeQuery` scoping rows to `context.user` — there is none
+ * here — or an `afterRead` rewriting a file field would hide a reference, and
+ * the file it names would be deleted as unused. Such a collection is
+ * returned as unscanned instead.
  */
 export declare function removeReferencedKeys(keys: Set<string>, collections: readonly CollectionConfig[], driverFor: (collection: CollectionConfig) => DataDriver | undefined, options?: {
     pageSize?: number;
+    globalCallbacks?: CollectionCallbacks;
+    /** Counted into as it goes, and `onProgress` called after each page. */
+    progress?: ScanProgress;
+    onProgress?: () => void;
+    /** Checked between pages: an aborted scan stops, and throws. */
+    signal?: AbortSignal;
 }): Promise<{
     scanned: string[];
     unscanned: UnscannedCollection[];
 }>;
+/** How row history is named among the scanned and unscanned collections. */
+export declare const HISTORY_SCAN_NAME = "(row history)";
 /** What `findOrphans` found. */
 export interface OrphanReport {
     /** Objects in the source, internal ones aside. */
@@ -80,6 +101,42 @@ export interface OrphanReport {
     scanned: string[];
     unscanned: UnscannedCollection[];
 }
+/** Row history, as a scan reads it. */
+export interface StoredHistory {
+    scanStoredValues?(pageSize?: number): AsyncIterable<unknown[]>;
+}
+/** Where references to stored files are read from: every row, and history. */
+export interface ReferenceSources {
+    collections: readonly CollectionConfig[];
+    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+    /** The callbacks every collection runs, which may scope or rewrite its reads. */
+    globalCallbacks?: CollectionCallbacks;
+    /**
+     * Row history, when the backend keeps it: a revert restores the values an
+     * entry holds, so a file only history names is still in use. One that
+     * cannot be read is reported unscanned, as {@link HISTORY_SCAN_NAME}.
+     */
+    history?: StoredHistory;
+}
+/** How far a scan has got. Counted into in place, so a caller can report it while it runs. */
+export interface ScanProgress {
+    phase: "listing" | "rows" | "history" | "deleting" | "done";
+    /** Objects listed in the source so far. */
+    filesScanned: number;
+    /** Rows read so far, over every collection. */
+    rowsScanned: number;
+    /** History entries read so far. */
+    historyEntriesScanned: number;
+    /** Collections finished, read or not. */
+    collectionsScanned: number;
+    collectionsTotal: number;
+    /** The collection being read now. */
+    currentCollection?: string;
+    /** The collections that could not be read, as they are found. */
+    unscanned: UnscannedCollection[];
+}
+/** A progress record at the start of a scan. */
+export declare function emptyScanProgress(): ScanProgress;
 /**
  * The objects of one source that no row names.
  *
@@ -87,13 +144,52 @@ export interface OrphanReport {
  *        an orphan: the admin panel uploads a file before the row that names it
  *        is saved. One whose age the listing does not say is not either.
  */
-export declare function findOrphans(options: {
+export declare function findOrphans(options: ReferenceSources & {
     controller: StorageController;
-    collections: readonly CollectionConfig[];
-    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
     olderThanMs: number;
     now?: number;
+    /** Counted into as the scan goes; `onProgress` is called after each page. */
+    progress?: ScanProgress;
+    onProgress?: () => void;
+    /** Checked between pages: an aborted scan stops, and throws. */
+    signal?: AbortSignal;
 }): Promise<OrphanReport>;
+/** What deleting a scan's orphans did. */
+export interface OrphanDeletion {
+    deleted: string[];
+    /** Candidates not deleted, because something changed since the scan. */
+    kept: {
+        key: string;
+        reason: string;
+    }[];
+    failed: {
+        key: string;
+        error: string;
+    }[];
+    /** Collections the re-check could not read; when any is, nothing was deleted. */
+    unscanned: UnscannedCollection[];
+}
+/**
+ * Delete the orphans an earlier scan found — each only if it is still one.
+ *
+ * Every row and history entry is read again, against the candidates alone
+ * (the source is not listed again): a row written since the scan may name one
+ * now. When a collection cannot be read, nothing is deleted. Then, right
+ * before each delete, the object is asked for again: one that is gone, was
+ * written again since the scan (another size or time), or is now inside the
+ * grace period is kept.
+ */
+export declare function deleteScannedOrphans(options: ReferenceSources & {
+    controller: StorageController;
+    candidates: readonly StoredObjectEntry[];
+    olderThanMs: number;
+    now?: () => number;
+    progress?: ScanProgress;
+    onProgress?: () => void;
+    /** Called after each file deleted. */
+    onDeleted?: (key: string) => void;
+    signal?: AbortSignal;
+}): Promise<OrphanDeletion>;
 /** What happened to one object in a move. */
 export interface MovedObject {
     key: string;
@@ -124,3 +220,39 @@ export declare function moveObjects(options: {
     moved: MovedObject[];
     cursor?: string;
 }>;
+/** A file a move did not move, and why it counts as not moved. */
+export interface NotMovedObject {
+    key: string;
+    reason: string;
+}
+/**
+ * List the source again after a move and name every file it did not move,
+ * `limit` source objects per call; hand the returned `cursor` back for the
+ * next ones.
+ *
+ * Defence in depth: a move reports what its own walk saw, and a walk that
+ * skipped files (as the local listing's page token once did, over a folder
+ * the move was emptying) reported success over the half it moved. A fresh
+ * listing does not share the walk's state. With `deleteSource`, every file
+ * still in the source is not moved; without it, a file the target holds no
+ * copy of the same size of.
+ */
+export declare function verifyMove(options: {
+    from: StorageController;
+    to: StorageController;
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    deleteSource?: boolean;
+}): Promise<{
+    checked: number;
+    notMoved: NotMovedObject[];
+    cursor?: string;
+}>;
+/**
+ * Whether two sources store in the same place — one bucket or directory under
+ * two names. Asked by their `storageLocation` when both can say; otherwise by
+ * a probe object written to `a` under the internal folder, looked for in `b`,
+ * and deleted.
+ */
+export declare function storesInSamePlace(a: StorageController, b: StorageController): Promise<boolean>;

package/dist/storage/orphan-scans.d.ts

@@ -0,0 +1,120 @@
+import type { CollectionCallbacks, CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { JobQueueClient } from "../jobs/types.js";
+import type { StorageController } from "./types.js";
+import type { StorageRegistry } from "./storage-registry.js";
+import { type OrphanReport, type ScanProgress, type StoredHistory } from "./maintenance.js";
+/** The job task a scan, or a scan's delete, runs as. Frozen: workers of another release claim it by name. */
+export declare const STORAGE_ORPHANS_TASK = "storage.orphans";
+/** Where scan records are kept inside the scanned source. */
+export declare const ORPHAN_SCAN_FOLDER = "_rebase/maintenance/orphan-scans";
+/**
+ * How long after it completed a scan's result may still be deleted from.
+ * Every candidate is checked again before it goes, so this is not what keeps
+ * a file in use; it keeps a delete acting on what the person just read.
+ */
+export declare const ORPHAN_SCAN_TTL_MS: number;
+/**
+ * A scan, or a delete, that has written no progress for this long is reported
+ * failed: the process running it stopped — a deploy, a crash — and nothing
+ * else will finish it. Progress is written at least once a page.
+ */
+export declare const ORPHAN_SCAN_STALL_MS: number;
+/** The default grace period: an upload whose row is not saved yet is a day old at most. */
+export declare const DEFAULT_OLDER_THAN_HOURS = 24;
+/** Who runs a scan: the job queue's workers, or the server process that was asked. */
+export type OrphanScanRunner = "worker" | "in-process";
+export type OrphanScanStatus = "queued" | "running" | "completed" | "failed";
+/** A delete from a completed scan, as its record holds it. */
+export interface OrphanScanDeletion {
+    status: OrphanScanStatus;
+    runner: OrphanScanRunner;
+    jobId?: string;
+    requestedAt: string;
+    startedAt?: string;
+    updatedAt: string;
+    completedAt?: string;
+    progress: ScanProgress & {
+        candidates: number;
+        deleted: number;
+    };
+    result?: {
+        deleted: string[];
+        kept: {
+            key: string;
+            reason: string;
+        }[];
+        failed: {
+            key: string;
+            error: string;
+        }[];
+    };
+    error?: string;
+    /** Set on the way out when a running delete has stopped reporting. */
+    note?: string;
+}
+/** A scan's record: what `GET /orphans/scans/:id` answers. */
+export interface OrphanScanState {
+    id: string;
+    storageId: string;
+    olderThanHours: number;
+    runner: OrphanScanRunner;
+    jobId?: string;
+    status: OrphanScanStatus;
+    createdAt: string;
+    startedAt?: string;
+    updatedAt: string;
+    completedAt?: string;
+    progress: ScanProgress;
+    /** The report, once completed: what the synchronous `GET /orphans` answered. */
+    result?: OrphanReport;
+    error?: string;
+    /** Said on the way out, never stored: why a queued scan may not have started, or that one stalled. */
+    note?: string;
+    deletion?: OrphanScanDeletion;
+}
+/** A `storage.orphans` job's payload. */
+export interface OrphanScanTaskPayload {
+    scanId: string;
+    storageId: string;
+    mode: "scan" | "delete";
+}
+export interface OrphanScanServiceConfig {
+    registry?: StorageRegistry;
+    controller?: StorageController;
+    /** The collections whose rows are read for references, read when a scan runs. */
+    collections: () => readonly CollectionConfig[];
+    /** The unscoped driver serving a collection. See `StorageMaintenanceRoutesConfig.driverFor`. */
+    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+    globalCallbacks?: () => CollectionCallbacks | undefined;
+    history?: StoredHistory;
+    /**
+     * The durable job queue, read when a scan starts: present, the scan is a
+     * `storage.orphans` job its workers run; absent, it runs in this process.
+     */
+    jobs?: () => JobQueueClient | undefined;
+    /** For tests. */
+    now?: () => number;
+}
+export interface OrphanScanService {
+    /** Record a scan and set it going. Resolves with its record, `queued`. */
+    start(options: {
+        storageId?: string;
+        olderThanHours?: number;
+    }): Promise<OrphanScanState>;
+    /** A scan's record, or `undefined` when this source holds none by that id. */
+    status(storageId: string | undefined, id: string): Promise<OrphanScanState | undefined>;
+    /** Start deleting a completed scan's orphans. Throws the refusal when it may not. */
+    requestDeletion(storageId: string | undefined, id: string): Promise<OrphanScanState>;
+    /** Run a `storage.orphans` job: the scan, or its delete. */
+    runTask(payload: OrphanScanTaskPayload, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * The storage source a request names, or the 404 that lists the ones served.
+ */
+export declare function resolveStorageSource(sources: {
+    registry?: StorageRegistry;
+    controller?: StorageController;
+}, rawId: unknown, label: string): StorageController;
+/** `olderThanHours` as a request sends it, checked. */
+export declare function parseOlderThanHours(raw: string | number | undefined): number;
+export declare function createOrphanScanService(config: OrphanScanServiceConfig): OrphanScanService;

package/dist/storage/types.d.ts

@@ -210,6 +210,17 @@ export interface StorageController {
      * when the caller names none, and each provider maps it to its own.
      */
     knownBuckets?(): string[];
+    /**
+     * Where this controller's default bucket physically is, as a string two
+     * controllers return alike exactly when they store in the same place: a
+     * resolved directory, an endpoint and bucket.
+     *
+     * Two sources declared over one bucket or directory are one store under
+     * two names, and `rebase storage move --delete-source` between them found
+     * every object "already there" — it is the same object — and deleted it
+     * from both. A controller without this is found out by a probe object.
+     */
+    storageLocation?(): string;
     /**
      * The largest file this controller accepts, in bytes.
      *

package/dist/strings.es-B7QLnHh2.js

@@ -0,0 +1,96 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+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 { suggestNearMiss as n, toSnakeCase as r, splitSearchTerms as t };
+
+//# sourceMappingURL=strings.es-B7QLnHh2.js.map

package/dist/strings.es-B7QLnHh2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.es-B7QLnHh2.js","names":[],"sources":["../../utils/dist/strings.es.js"],"sourcesContent":["//#region src/strings.ts\nvar tokenizeRegex = /[A-Z]{2,}(?=[A-Z][a-z]|\\b)|[A-Z]?[a-z]+|[0-9]+(?:[a-z](?![a-z]))?|[A-Z]/g;\nvar toKebabCase = (str) => {\n\tif (!str || typeof str !== \"string\") return \"\";\n\tconst regExpMatchArray = str.match(tokenizeRegex);\n\tif (!regExpMatchArray) return \"\";\n\treturn regExpMatchArray.map((x) => x.toLowerCase()).join(\"-\");\n};\nvar snakeCaseRegex = tokenizeRegex;\nvar toSnakeCase = (str) => {\n\tif (!str || typeof str !== \"string\") return \"\";\n\tconst regExpMatchArray = str.match(snakeCaseRegex);\n\tif (!regExpMatchArray) return \"\";\n\treturn regExpMatchArray.map((x) => x.toLowerCase()).join(\"_\");\n};\nfunction camelCase(str) {\n\tif (!str) return \"\";\n\tif (str.length === 1) return str.toLowerCase();\n\tconst parts = str.split(/[-_ ]+/).filter(Boolean);\n\tif (parts.length === 0) return \"\";\n\treturn parts[0].toLowerCase() + parts.slice(1).map((part) => part.charAt(0).toUpperCase() + part.substring(1).toLowerCase()).join(\"\");\n}\n/**\n* A random base-36 string of exactly `strLength` characters.\n*\n* Not `Math.random().toString(36).slice(2, 2 + strLength)`: that has no\n* guaranteed length. Base-36 of a double drops trailing zeros, so the source\n* string is short about once in 36 calls and the slice quietly returns fewer\n* characters than asked for — `randomString(10)` returning 9. These values\n* prefix uploaded filenames to keep them apart, so a short one is a likelier\n* collision, and it fails at the rate that makes a test look flaky.\n*/\nfunction randomString(strLength = 5) {\n\tconst alphabet = \"0123456789abcdefghijklmnopqrstuvwxyz\";\n\tlet result = \"\";\n\tfor (let i = 0; i < strLength; i++) result += alphabet.charAt(Math.floor(Math.random() * 36));\n\treturn result;\n}\nfunction randomColor() {\n\treturn Math.floor(Math.random() * 16777215).toString(16);\n}\nfunction slugify(text, separator = \"_\", lowercase = true) {\n\tif (!text) return \"\";\n\tconst from = \"ãàáäâẽèéëêìíïîõòóöôùúüûñç·/_,:;-\";\n\tconst to = `aaaaaeeeeeiiiiooooouuuunc${separator}${separator}${separator}${separator}${separator}${separator}${separator}`;\n\tfor (let i = 0, l = 32; i < l; i++) text = text.replace(new RegExp(from.charAt(i), \"g\"), to.charAt(i));\n\ttext = text.toString().trim().replace(/^\\s+|\\s+$/g, \"\").replace(/\\s+/g, separator).replace(/&/g, separator).replace(/[^\\w\\\\-]+/g, \"\").replace(new RegExp(\"\\\\\" + separator + \"\\\\\" + separator + \"+\", \"g\"), separator);\n\treturn lowercase ? text.toLowerCase() : text;\n}\nfunction unslugify(slug) {\n\tif (!slug) return \"\";\n\tif (slug.includes(\"-\") || slug.includes(\"_\") || !slug.includes(\" \")) return slug.replace(/[-_]/g, \" \").replace(/\\w\\S*/g, function(txt) {\n\t\treturn txt.charAt(0).toUpperCase() + txt.substring(1);\n\t}).trim();\n\telse return slug.trim();\n}\n/**\n* Are these two identifiers one edit apart, ignoring case?\n*\n* Tight on purpose. A suggester that fires on two edits offers `columnWidth`\n* for `colWith` and `readOnly` for `required`, and a \"did you mean\" that is\n* usually wrong teaches people to stop reading them. One edit covers what\n* actually happens — a dropped letter (`multilne`), a doubled one, a transposed\n* pair (`validaton`), a wrong case — and nothing else.\n*\n* Lives here rather than beside either caller because both the CLI's manifest\n* reader and the server's collection validator answer the same question about\n* an unknown key, and two copies of a similarity rule is two rules the moment\n* one of them is tuned.\n*/\nfunction isNearMiss(a, b) {\n\tconst x = a.toLowerCase();\n\tconst y = b.toLowerCase();\n\tif (x === y) return true;\n\tif (Math.abs(x.length - y.length) > 1) return false;\n\tconst [shorter, longer] = x.length <= y.length ? [x, y] : [y, x];\n\tlet i = 0;\n\tlet j = 0;\n\tlet edits = 0;\n\twhile (i < shorter.length && j < longer.length) {\n\t\tif (shorter[i] === longer[j]) {\n\t\t\ti++;\n\t\t\tj++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (++edits > 1) return false;\n\t\tif (shorter.length === longer.length) i++;\n\t\tj++;\n\t}\n\treturn edits + (longer.length - j) + (shorter.length - i) <= 1;\n}\n/**\n* The key in `known` that `key` was probably meant to be, if any.\n*\n* `undefined` when nothing is close — which is the common case for a key that\n* is simply from a newer version, and the reason the caller must be able to say\n* \"unknown\" without saying \"wrong\".\n*/\nfunction suggestNearMiss(known, key) {\n\treturn known.find((candidate) => isNearMiss(candidate, key));\n}\nfunction prettifyIdentifier(input) {\n\tif (!input) return \"\";\n\tlet text = input;\n\ttext = text.replace(/([a-z])([A-Z])|([A-Z])([A-Z][a-z])/g, \"$1$3 $2$4\");\n\ttext = text.replace(/[_-]+/g, \" \");\n\treturn text.trim().replace(/\\b\\w/g, (char) => char.toUpperCase());\n}\n/**\n* How many terms one search string is allowed to contribute.\n*\n* Every term multiplies the work: the substring fallback compiles to one\n* `ILIKE '%term%'` per term *per searchable column*, evaluated per row on a\n* sequential scan. Eight is far past what a person types into a search box and\n* still bounds a pasted paragraph to a fixed number of predicates. Terms past\n* the cap are dropped rather than rejected — dropping only widens the result\n* set, and a search box that errors on a long paste is worse than one that\n* matches on its first eight words.\n*/\nvar MAX_SEARCH_TERMS = 8;\n/**\n* The terms a user meant when they typed into a search box.\n*\n* A search box is not a substring box. Typing `sebastian melendez` on a\n* collection whose name is split across `first_name` and `last_name` has to\n* find the row, and matching the whole string against each field separately\n* cannot: no single column holds both words. Splitting on whitespace and\n* requiring *every* term to match *some* field is what does, and it is what\n* `websearch_to_tsquery` already does for collections that declared a `search`\n* block — so this is also what keeps the two search paths answering the same\n* question.\n*\n* It fixes the trailing space too: `sebastian ` matched nothing at all, because\n* the space was part of the pattern.\n*\n* A double-quoted run is one term, again matching the full-text path, so a\n* caller who really does want the phrase can ask for it. An unbalanced quote is\n* stripped rather than honoured — the alternative is that everything after a\n* stray `\"` silently becomes one long term that matches nothing.\n*\n* Returns an empty array for a string with no terms in it at all (whitespace,\n* or nothing but quotes); the caller decides what an empty search means, since\n* only it knows whether \"no constraint\" or \"no rows\" is the safe reading.\n*/\nfunction splitSearchTerms(searchString, maxTerms = MAX_SEARCH_TERMS) {\n\tconst terms = [];\n\tconst pattern = /\"([^\"]*)\"|(\\S+)/g;\n\tlet match;\n\twhile ((match = pattern.exec(searchString)) !== null) {\n\t\tconst term = (match[1] ?? match[2].replace(/\"/g, \"\")).trim();\n\t\tif (!term) continue;\n\t\tterms.push(term);\n\t\tif (terms.length >= maxTerms) break;\n\t}\n\treturn terms;\n}\n//#endregion\nexport { MAX_SEARCH_TERMS, camelCase, isNearMiss, prettifyIdentifier, randomColor, randomString, slugify, splitSearchTerms, suggestNearMiss, toKebabCase, toSnakeCase, unslugify };\n\n//# sourceMappingURL=strings.es.js.map"],"mappings":";;;;AAQA,IAAI,iBAAiB;AACrB,IAAI,eAAe,QAAQ;CAC1B,IAAI,CAAC,OAAO,OAAO,QAAQ,UAAU,OAAO;CAC5C,MAAM,mBAAmB,IAAI,MAAM,cAAc;CACjD,IAAI,CAAC,kBAAkB,OAAO;CAC9B,OAAO,iBAAiB,KAAK,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,GAAG;AAC7D;;;;;;;;;;;;;;;AAwDA,SAAS,WAAW,GAAG,GAAG;CACzB,MAAM,IAAI,EAAE,YAAY;CACxB,MAAM,IAAI,EAAE,YAAY;CACxB,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,KAAK,IAAI,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,OAAO;CAC9C,MAAM,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC;CAC/D,IAAI,IAAI;CACR,IAAI,IAAI;CACR,IAAI,QAAQ;CACZ,OAAO,IAAI,QAAQ,UAAU,IAAI,OAAO,QAAQ;EAC/C,IAAI,QAAQ,OAAO,OAAO,IAAI;GAC7B;GACA;GACA;EACD;EACA,IAAI,EAAE,QAAQ,GAAG,OAAO;EACxB,IAAI,QAAQ,WAAW,OAAO,QAAQ;EACtC;CACD;CACA,OAAO,SAAS,OAAO,SAAS,MAAM,QAAQ,SAAS,MAAM;AAC9D;;;;;;;;AAQA,SAAS,gBAAgB,OAAO,KAAK;CACpC,OAAO,MAAM,MAAM,cAAc,WAAW,WAAW,GAAG,CAAC;AAC5D;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAS,iBAAiB,cAAc,WAAA,GAA6B;CACpE,MAAM,QAAQ,CAAC;CACf,MAAM,UAAU;CAChB,IAAI;CACJ,QAAQ,QAAQ,QAAQ,KAAK,YAAY,OAAO,MAAM;EACrD,MAAM,QAAQ,MAAM,MAAM,MAAM,EAAE,CAAC,QAAQ,MAAM,EAAE,EAAA,CAAG,KAAK;EAC3D,IAAI,CAAC,MAAM;EACX,MAAM,KAAK,IAAI;EACf,IAAI,MAAM,UAAU,UAAU;CAC/B;CACA,OAAO;AACR"}

package/dist/{upload-validation-I9cCUBIW.js → upload-validation-Bgo626uY.js}

@@ -2,7 +2,7 @@ import { createRequire as __rebaseCreateRequire } from "module";
 import __rebaseProcess from "process";
 globalThis.process ??= __rebaseProcess;
 __rebaseCreateRequire(import.meta.url);
-import { t as ApiError } from "./errors-_ytoGi8A.js";
+import { t as ApiError } from "./errors-OMWkKSH-.js";
 import fs from "node:fs";
 //#region src/storage/types.ts
 /**
@@ -169,4 +169,4 @@ function validateUploadedFile(file, maxSize, allowedMimeTypes) {
 //#endregion
 export { readStreamFully as a, DOCUMENT_MIME_TYPES as c, fileWebStream as i, IMAGE_MIME_TYPES as l, bufferWebStream as n, webStreamFrom as o, bytesView as r, DEFAULT_MAX_FILE_SIZE as s, validateUploadedFile as t };
 
-//# sourceMappingURL=upload-validation-I9cCUBIW.js.map
+//# sourceMappingURL=upload-validation-Bgo626uY.js.map

package/dist/upload-validation-Bgo626uY.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-validation-Bgo626uY.js","names":[],"sources":["../src/storage/types.ts","../src/storage/streams.ts","../src/storage/upload-validation.ts"],"sourcesContent":["/**\n * Storage configuration and types for Rebase backend\n */\n\nimport { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, DownloadMetadata, StorageListResult, StorageReference } from \"@rebasepro/types\";\n\n/**\n * Local filesystem storage configuration\n */\nexport interface LocalStorageConfig {\n    type: \"local\";\n    /** Base directory for file storage (e.g., './uploads') */\n    basePath: string;\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types (if not set, all types allowed) */\n    allowedMimeTypes?: string[];\n    /** Base URL for generating download URLs (default: auto-detected from request) */\n    baseUrl?: string;\n    /**\n     * Set when this local backend stands in for an object store the source\n     * declared and nothing bound — `bucket(\"media\", { engine: \"s3\" })` with no\n     * `S3_BUCKET__MEDIA` in a development process. Names the engine it stands\n     * in for, so boot can say so and `rebase status` can show it. Never set in\n     * production, where an unbound object store stays unbound.\n     */\n    standsInFor?: string;\n    /**\n     * Set when nothing chose this backend: no `STORAGE_TYPE` and no declared\n     * engine, so local disk is only the default a source falls back to.\n     * Production drops a local backend either way. This only decides how that\n     * is reported: an implicit default being dropped means the project uses no\n     * storage, which is not a misconfiguration.\n     */\n    implicit?: boolean;\n}\n\n/**\n * S3-compatible storage configuration (works with AWS S3 and MinIO)\n */\nexport interface S3StorageConfig {\n    type: \"s3\";\n    /** S3 bucket name */\n    bucket: string;\n    /** AWS region (e.g., 'us-east-1') */\n    region?: string;\n    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */\n    endpoint?: string;\n    /** AWS access key ID */\n    accessKeyId: string;\n    /** AWS secret access key */\n    secretAccessKey: string;\n    /** Use path-style URLs (required for MinIO) */\n    forcePathStyle?: boolean;\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types (if not set, all types allowed) */\n    allowedMimeTypes?: string[];\n}\n\n/**\n * Google Cloud Storage configuration (works with GCS and Firebase Storage)\n */\nexport interface GCSStorageConfig {\n    type: \"gcs\";\n    /** GCS bucket name (e.g. \"my-project.appspot.com\" for Firebase Storage) */\n    bucket: string;\n    /** GCP project ID (optional, auto-detected from credentials) */\n    projectId?: string;\n    /** Path to service account JSON key file */\n    keyFilename?: string;\n    /** Service account credentials object (alternative to keyFilename) */\n    credentials?: { client_email: string; private_key: string; project_id?: string };\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types */\n    allowedMimeTypes?: string[];\n}\n\n/**\n * Storage configuration — local filesystem, S3-compatible, or Google Cloud Storage.\n *\n * **Built-in providers:**\n * - `local` — Zero-config filesystem storage. Great for dev and single-server deployments (Hetzner, bare metal).\n * - `s3` — Any S3-compatible provider. AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,\n *           Backblaze B2, DigitalOcean Spaces, and even GCS (via its S3-compatible interoperability API).\n * - `gcs` — Native Google Cloud Storage / Firebase Storage via `@google-cloud/storage`.\n *\n * **Custom providers:**\n * For other cloud storage (Azure Blob, etc.), implement the `StorageController`\n * interface and pass the instance directly to the `storage` config.\n */\nexport type BackendStorageConfig = LocalStorageConfig | S3StorageConfig | GCSStorageConfig;\n\n/** What a storage request is trying to do to an object. */\nexport type {\n    StorageOperation,\n    StorageAuthorizeUser,\n    StorageAuthorizeContext,\n    StorageAuthorizeData,\n    StorageAuthorize\n} from \"@rebasepro/types\";\n\n/**\n * How the server writes an object. See {@link StorageController.putObject}.\n */\nexport interface PutObjectOptions {\n    /**\n     * Hold this write to the controller's upload limits: `maxFileSize` and\n     * `allowedMimeTypes`. Defaults to `true`.\n     *\n     * Those limits say what a user may upload. A write the server makes for\n     * itself, such as a database backup, passes `false`. A dump is neither of\n     * an allowed type nor, past a small database, under 50 MB. The upload\n     * routes never pass it.\n     */\n    uploadLimits?: boolean;\n}\n\n/**\n * Storage controller interface for backend implementations\n */\nexport interface StorageController {\n    /**\n     * Upload an object.\n     *\n     * A write is held to the controller's upload limits — `maxFileSize` and\n     * `allowedMimeTypes` — unless `options.uploadLimits` is `false`. Only the\n     * server's own writes pass that; nothing a request sends reaches it.\n     */\n    putObject(props: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;\n\n    /**\n     * Get a download URL (signed URL equivalent) for an object.\n     *\n     * For server-side code only: no route hands this URL to a client. A\n     * client reads a private object through `/file/*` with the download\n     * token `GET /metadata/*` mints. The built-in S3 and GCS controllers sign\n     * it for an hour.\n     */\n    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;\n\n    /**\n     * Describe an object — size, type, custom metadata — without producing a\n     * URL for it, or `null` when there is no such object.\n     *\n     * `GET /metadata/*` wants only this: the client builds its own `/file/*`\n     * URL and spends the download token the route mints. Asking\n     * `getSignedUrl` for it made every metadata read sign a URL nobody used,\n     * and on GCS signing is not free — without a key file the client asks the\n     * IAM Credentials API to sign, which needs `iam.serviceAccounts.signBlob`\n     * on the runtime account itself. Cloud Run does not grant that, so every\n     * private object answered 500 there.\n     *\n     * A controller that does not implement this keeps the old behaviour: the\n     * route falls back to `getSignedUrl` and reads its `metadata`.\n     */\n    getMetadata?(key: string, bucket?: string): Promise<DownloadMetadata | null>;\n\n    /**\n     * Get object as a File\n     */\n    getObject(key: string, bucket?: string): Promise<File | null>;\n\n    /**\n     * Describe an object for serving it — its size, stored type and version —\n     * without reading its bytes, or `null` when there is no such object.\n     *\n     * Optional, together with {@link getObjectStream}. A controller that has\n     * both is served streamed: `GET /file/*` answers a `304`, a `416`, a `HEAD`\n     * and a cached image rendition from this alone, and otherwise reads only\n     * the bytes it sends — the requested range, a chunk at a time. One without\n     * them is served through {@link getObject}, which holds the whole object in\n     * memory for every request, a `Range` request for one megabyte included.\n     */\n    statObject?(key: string, bucket?: string): Promise<StoredObjectInfo | null>;\n\n    /**\n     * Read an object, or one byte range of it, as a stream, or `null` when\n     * there is no such object. See {@link statObject}.\n     *\n     * The stream holds a file or a connection until it is read to the end or\n     * cancelled, so a caller that decides not to read it must cancel it.\n     */\n    getObjectStream?(key: string, options?: { bucket?: string; range?: StoredObjectRange }): Promise<StoredObjectStream | null>;\n\n    /**\n     * Delete an object\n     */\n    deleteObject(key: string, bucket?: string): Promise<void>;\n\n    /**\n     * List objects in a prefix\n     */\n    listObjects(prefix: string, options?: {\n        bucket?: string;\n        maxResults?: number;\n        pageToken?: string;\n    }): Promise<StorageListResult>;\n\n    /**\n     * Get the storage provider identifier.\n     *\n     * Built-in values are `'local'` and `'s3'`. Custom implementations\n     * should return their own identifier (e.g. `'gcs'`, `'azure'`).\n     */\n    getType(): string;\n\n    /**\n     * The buckets this controller serves, if it knows.\n     *\n     * The `bucket` a request may name is not a free-text field: on S3 and GCS it\n     * goes straight to the provider, so an unvalidated one addresses *any*\n     * bucket the deployment's credentials can reach, and locally it names a\n     * directory the framework would create on demand. Either way, a caller who\n     * mistypes it gets \"file not found\" — the same answer as a missing object —\n     * with nothing to say the bucket was the problem.\n     *\n     * So a controller that knows its buckets says so, and the routes refuse\n     * anything else with `UNKNOWN_STORAGE_SOURCE` naming what is served. A\n     * controller that does not implement this keeps the old behaviour and is\n     * handed whatever the caller wrote — a custom implementation may address\n     * buckets this framework has no way to enumerate.\n     *\n     * `\"default\"` is always among them: it is the logical name every route uses\n     * when the caller names none, and each provider maps it to its own.\n     */\n    knownBuckets?(): string[];\n\n    /**\n     * Where this controller's default bucket physically is, as a string two\n     * controllers return alike exactly when they store in the same place: a\n     * resolved directory, an endpoint and bucket.\n     *\n     * Two sources declared over one bucket or directory are one store under\n     * two names, and `rebase storage move --delete-source` between them found\n     * every object \"already there\" — it is the same object — and deleted it\n     * from both. A controller without this is found out by a probe object.\n     */\n    storageLocation?(): string;\n\n    /**\n     * The largest file this controller accepts, in bytes.\n     *\n     * Every door that takes a file reads it, so the number a client is told is\n     * the number it is held to: the upload route checks it before anything is\n     * stored, the resumable route checks it at creation — before the first\n     * chunk rather than after the last — and advertises it as `Tus-Max-Size`,\n     * and the server's upload body limit is the largest of them. A controller\n     * that does not implement this is held to the deployment-wide limit alone.\n     */\n    maxFileSize?(): number;\n}\n\n/**\n * What serving an object needs to know before deciding whether to read it.\n * See {@link StorageController.statObject}.\n */\nexport interface StoredObjectInfo {\n    /** The whole object's size in bytes. */\n    size: number;\n    /** The stored content type — the uploader's claim, not a sniffed one. */\n    contentType: string;\n    /**\n     * The object's own modification time, in milliseconds since the epoch.\n     * The routes build `ETag`, `Last-Modified` and the transform cache key from\n     * it, so it must be the object's version, not the time of the read.\n     */\n    lastModified: number;\n}\n\n/** An inclusive byte range, as `Range: bytes=start-end` names one. */\nexport interface StoredObjectRange {\n    start: number;\n    end: number;\n}\n\n/** An object's bytes as a stream. See {@link StorageController.getObjectStream}. */\nexport interface StoredObjectStream extends StoredObjectInfo {\n    /** The bytes: the range when {@link range} is set, the whole object otherwise. */\n    stream: ReadableStream<Uint8Array>;\n    /**\n     * The range {@link stream} holds — the one asked for — or absent when it\n     * holds the whole object. A controller may answer a range with the whole\n     * object, as HTTP lets a server do; the caller then serves it whole.\n     */\n    range?: StoredObjectRange;\n}\n\n/**\n * Default maximum file size (50MB)\n */\nexport const DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;\n\n/**\n * Common image MIME types\n */\nexport const IMAGE_MIME_TYPES = [\n    \"image/jpeg\",\n    \"image/png\",\n    \"image/gif\",\n    \"image/webp\",\n    \"image/svg+xml\",\n    \"image/bmp\",\n    \"image/tiff\"\n];\n\n/**\n * Common document MIME types\n */\nexport const DOCUMENT_MIME_TYPES = [\n    \"application/pdf\",\n    \"application/msword\",\n    \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    \"application/vnd.ms-excel\",\n    \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n    \"application/vnd.ms-powerpoint\",\n    \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n    \"text/plain\",\n    \"text/csv\"\n];\n","/**\n * Moving object bytes without holding them.\n *\n * A stored object can be as large as the deployment's `maxFileSize` allows — a\n * video, a database dump — and the paths that used to read one whole (a\n * `File`, an `arrayBuffer()`, a `Buffer.concat`) held it three or four times\n * over per request. These helpers are what the streamed paths share instead.\n */\nimport fs from \"node:fs\";\n\n/** Anything that hands over bytes a chunk at a time: a Node readable, an SDK body. */\ntype ByteSource = AsyncIterable<Uint8Array>;\n\n/**\n * A byte source as a web stream that reads a chunk only when the consumer asks\n * for one, and releases the source when the consumer stops early.\n *\n * Pull-based with a zero high-water mark, so nothing is read ahead of the\n * reader: a slow client holds one chunk, not a queue of them. A source given\n * as a function is opened on the first read, which keeps a stream nobody reads\n * — a `HEAD`, a 304 decided late — from holding a file descriptor or a\n * connection open. Cancelling (a client that disconnects mid-download)\n * returns the iterator, which destroys a Node stream and so closes its file or\n * socket.\n */\nexport function webStreamFrom(source: ByteSource | (() => ByteSource)): ReadableStream<Uint8Array> {\n    let iterator: AsyncIterator<Uint8Array> | undefined;\n    const open = (): AsyncIterator<Uint8Array> => {\n        iterator ??= (typeof source === \"function\" ? source() : source)[Symbol.asyncIterator]();\n        return iterator;\n    };\n    return new ReadableStream<Uint8Array>({\n        async pull(controller) {\n            try {\n                const next = await open().next();\n                if (next.done) controller.close();\n                else controller.enqueue(next.value);\n            } catch (err) {\n                controller.error(err);\n            }\n        },\n        async cancel() {\n            // A source never opened has nothing to release — and opening it\n            // now only to close it would be the cost this avoids.\n            if (!iterator && typeof source === \"function\") return;\n            try {\n                await open().return?.();\n            } catch {\n                // Already failed or closed; either way it is released.\n            }\n        }\n    }, { highWaterMark: 0 });\n}\n\n/**\n * A file on disk, or an inclusive byte range of it, as a web stream. The file\n * is opened on the first read; see {@link webStreamFrom}.\n */\nexport function fileWebStream(filePath: string, range?: { start: number; end: number }): ReadableStream<Uint8Array> {\n    return webStreamFrom(() => fs.createReadStream(filePath, range ? { start: range.start, end: range.end } : {}));\n}\n\n/** A buffer already in memory as a web stream of views onto it, never copies. */\nexport function bufferWebStream(bytes: Uint8Array, chunkSize = 64 * 1024): ReadableStream<Uint8Array> {\n    let offset = 0;\n    return new ReadableStream<Uint8Array>({\n        pull(controller) {\n            if (offset >= bytes.byteLength) {\n                controller.close();\n                return;\n            }\n            const end = Math.min(offset + chunkSize, bytes.byteLength);\n            controller.enqueue(bytes.subarray(offset, end));\n            offset = end;\n        }\n    }, { highWaterMark: 0 });\n}\n\n/**\n * Read a stream into one buffer.\n *\n * For the one consumer that needs the whole object at once — an image decode.\n * With the size known the bytes are copied once, into a buffer of that size,\n * rather than collected and then concatenated (which holds them twice); a\n * stream that turns out longer or shorter than announced still comes back\n * whole and exact.\n */\nexport async function readStreamFully(stream: ReadableStream<Uint8Array>, expectedSize?: number): Promise<Buffer> {\n    const reader = stream.getReader();\n    const target = expectedSize !== undefined && expectedSize > 0 ? Buffer.allocUnsafe(expectedSize) : undefined;\n    let offset = 0;\n    let overflow: Uint8Array[] | undefined;\n    try {\n        for (;;) {\n            const { done, value } = await reader.read();\n            if (done) break;\n            if (target && !overflow && offset + value.byteLength <= target.byteLength) {\n                target.set(value, offset);\n            } else {\n                overflow ??= target ? [target.subarray(0, offset)] : [];\n                overflow.push(value);\n            }\n            offset += value.byteLength;\n        }\n    } finally {\n        reader.releaseLock();\n    }\n    if (overflow) return Buffer.concat(overflow, offset);\n    if (!target) return Buffer.alloc(0);\n    return offset === target.byteLength ? target : target.subarray(0, offset);\n}\n\n/**\n * The bytes of a buffer as a `Uint8Array` the response APIs accept, without\n * copying them. `new Uint8Array(buffer)` copies; a view does not. Only a buffer\n * over shared memory — which nothing here produces — is copied.\n */\nexport function bytesView(bytes: Uint8Array): Uint8Array<ArrayBuffer> {\n    const backing = bytes.buffer;\n    return backing instanceof ArrayBuffer\n        ? new Uint8Array(backing, bytes.byteOffset, bytes.byteLength)\n        : new Uint8Array(bytes);\n}\n","/**\n * What every storage controller checks about a file before it stores it: the\n * source's own size cap and, when configured, its allowed content types.\n *\n * One function for the three controllers, which carried a copy each. Both\n * refusals are `ApiError`s, so they reach the caller as what they are. A plain\n * `Error` was a 500 \"Internal Server Error\" on `/upload` and a 502 on TUS —\n * after the client had sent every byte.\n */\n\nimport { ApiError } from \"../api/errors\";\n\nexport function validateUploadedFile(\n    file: { size: number; type: string },\n    maxSize: number,\n    allowedMimeTypes: string[] | undefined\n): void {\n    if (file.size > maxSize) {\n        throw new ApiError(\n            413,\n            \"PAYLOAD_TOO_LARGE\",\n            `File size ${file.size} exceeds this storage source's maximum of ${maxSize} bytes.`,\n            { size: file.size, maxFileSize: maxSize }\n        );\n    }\n\n    if (allowedMimeTypes && allowedMimeTypes.length > 0 && !allowedMimeTypes.includes(file.type)) {\n        // The code a property's `acceptedFiles` refusal answers with: to the\n        // caller, \"this source does not take this type\" is the same mistake.\n        throw ApiError.badRequest(\n            `File type ${file.type || \"(none)\"} is not allowed on this storage source. ` +\n            `Allowed types: ${allowedMimeTypes.join(\", \")}.`,\n            \"STORAGE_FILE_TYPE_REFUSED\",\n            { allowedMimeTypes, contentType: file.type }\n        );\n    }\n}\n"],"mappings":";;;;;;;;;;AAoSA,IAAa,wBAAwB,KAAK,OAAO;;;;AAKjD,IAAa,mBAAmB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;AACJ;;;;AAKA,IAAa,sBAAsB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACJ;;;;;;;;;;;;;;;;;;;;;;;ACvSA,SAAgB,cAAc,QAAqE;CAC/F,IAAI;CACJ,MAAM,aAAwC;EAC1C,cAAc,OAAO,WAAW,aAAa,OAAO,IAAI,OAAA,CAAQ,OAAO,cAAc,CAAC;EACtF,OAAO;CACX;CACA,OAAO,IAAI,eAA2B;EAClC,MAAM,KAAK,YAAY;GACnB,IAAI;IACA,MAAM,OAAO,MAAM,KAAK,CAAC,CAAC,KAAK;IAC/B,IAAI,KAAK,MAAM,WAAW,MAAM;SAC3B,WAAW,QAAQ,KAAK,KAAK;GACtC,SAAS,KAAK;IACV,WAAW,MAAM,GAAG;GACxB;EACJ;EACA,MAAM,SAAS;GAGX,IAAI,CAAC,YAAY,OAAO,WAAW,YAAY;GAC/C,IAAI;IACA,MAAM,KAAK,CAAC,CAAC,SAAS;GAC1B,QAAQ,CAER;EACJ;CACJ,GAAG,EAAE,eAAe,EAAE,CAAC;AAC3B;;;;;AAMA,SAAgB,cAAc,UAAkB,OAAoE;CAChH,OAAO,oBAAoB,GAAG,iBAAiB,UAAU,QAAQ;EAAE,OAAO,MAAM;EAAO,KAAK,MAAM;CAAI,IAAI,CAAC,CAAC,CAAC;AACjH;;AAGA,SAAgB,gBAAgB,OAAmB,YAAY,KAAK,MAAkC;CAClG,IAAI,SAAS;CACb,OAAO,IAAI,eAA2B,EAClC,KAAK,YAAY;EACb,IAAI,UAAU,MAAM,YAAY;GAC5B,WAAW,MAAM;GACjB;EACJ;EACA,MAAM,MAAM,KAAK,IAAI,SAAS,WAAW,MAAM,UAAU;EACzD,WAAW,QAAQ,MAAM,SAAS,QAAQ,GAAG,CAAC;EAC9C,SAAS;CACb,EACJ,GAAG,EAAE,eAAe,EAAE,CAAC;AAC3B;;;;;;;;;;AAWA,eAAsB,gBAAgB,QAAoC,cAAwC;CAC9G,MAAM,SAAS,OAAO,UAAU;CAChC,MAAM,SAAS,iBAAiB,KAAA,KAAa,eAAe,IAAI,OAAO,YAAY,YAAY,IAAI,KAAA;CACnG,IAAI,SAAS;CACb,IAAI;CACJ,IAAI;EACA,SAAS;GACL,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;GAC1C,IAAI,MAAM;GACV,IAAI,UAAU,CAAC,YAAY,SAAS,MAAM,cAAc,OAAO,YAC3D,OAAO,IAAI,OAAO,MAAM;QACrB;IACH,aAAa,SAAS,CAAC,OAAO,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC;IACtD,SAAS,KAAK,KAAK;GACvB;GACA,UAAU,MAAM;EACpB;CACJ,UAAU;EACN,OAAO,YAAY;CACvB;CACA,IAAI,UAAU,OAAO,OAAO,OAAO,UAAU,MAAM;CACnD,IAAI,CAAC,QAAQ,OAAO,OAAO,MAAM,CAAC;CAClC,OAAO,WAAW,OAAO,aAAa,SAAS,OAAO,SAAS,GAAG,MAAM;AAC5E;;;;;;AAOA,SAAgB,UAAU,OAA4C;CAClE,MAAM,UAAU,MAAM;CACtB,OAAO,mBAAmB,cACpB,IAAI,WAAW,SAAS,MAAM,YAAY,MAAM,UAAU,IAC1D,IAAI,WAAW,KAAK;AAC9B;;;;;;;;;;;;AC9GA,SAAgB,qBACZ,MACA,SACA,kBACI;CACJ,IAAI,KAAK,OAAO,SACZ,MAAM,IAAI,SACN,KACA,qBACA,aAAa,KAAK,KAAK,4CAA4C,QAAQ,UAC3E;EAAE,MAAM,KAAK;EAAM,aAAa;CAAQ,CAC5C;CAGJ,IAAI,oBAAoB,iBAAiB,SAAS,KAAK,CAAC,iBAAiB,SAAS,KAAK,IAAI,GAGvF,MAAM,SAAS,WACX,aAAa,KAAK,QAAQ,SAAS,yDACjB,iBAAiB,KAAK,IAAI,EAAE,IAC9C,6BACA;EAAE;EAAkB,aAAa,KAAK;CAAK,CAC/C;AAER"}

package/dist/utils/dev-dependency-command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `add -D <spec>` for the package the backend in `startDir` runs from, typed
+ * at the project root: `pnpm --dir backend add -D ts-morph@28.0.0` in a
+ * scaffold, `pnpm add -D ts-morph@28.0.0` where the backend is the project.
+ */
+export declare function devDependencyInstallCommand(spec: string, startDir?: string): string;
+/**
+ * How to turn on what needs `ts-morph`, as the end of a sentence that has
+ * said it is missing: "Run `pnpm --dir backend add -D ts-morph@28.0.0` from
+ * the project root, then restart the backend, to enable it."
+ *
+ * `pnpm`, never `npm`, in a pnpm project: running npm inside one rewrites
+ * node_modules into a hoisted layout pnpm then disagrees with (docs/bug-classes.md §5).
+ */
+export declare function tsMorphInstallSentence(startDir?: string): string;