sliftutils 1.4.17 → 1.4.19

package/index.d.ts

@@ -921,7 +921,7 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabaseBase" {
     export declare const noopReactiveDeps: ReactiveDeps;
     export type StorageFactory = (path: string) => Promise<FileStorage>;
     export type BulkDatabase2Config = {
-        triggerThrottleMs?: number;
+        maxTriggerThrottleMs?: number;
     };
     export declare class BulkDatabaseBase<T extends {
         key: string;
@@ -1396,6 +1396,7 @@ declare module "sliftutils/storage/FileFolderAPI" {
             write(value: Buffer): Promise<void>;
             close(): Promise<void>;
         }>;
+        getURL?(): Promise<string>;
     };
     export type DirectoryWrapper = {
         readonly kind: "directory";
@@ -1428,6 +1429,7 @@ declare module "sliftutils/storage/FileFolderAPI" {
                 arrayBuffer: () => Promise<ArrayBuffer>;
             };
         }>;
+        getURL(): Promise<string>;
         createWritable(config?: {
             keepExistingData?: boolean;
         }): Promise<{
@@ -1492,6 +1494,8 @@ declare module "sliftutils/storage/FileFolderAPI" {
         isRemote?: boolean;
     };
     export declare function wrapHandle(handle: DirectoryWrapper): FileStorage;
+    export declare function getFileURL(file: FileWrapper): Promise<string>;
+    export declare function disposeFileURL(url: string): void;
     export declare function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage>;
     export declare function tryToLoadPointer(pointer: string): Promise<DirectoryWrapper | undefined>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sliftutils",
-    "version": "1.4.17",
+    "version": "1.4.19",
     "main": "index.js",
     "license": "MIT",
     "files": [

package/storage/BulkDatabase2/BulkDatabaseBase.d.ts

@@ -17,7 +17,7 @@ export interface ReactiveDeps {
 export declare const noopReactiveDeps: ReactiveDeps;
 export type StorageFactory = (path: string) => Promise<FileStorage>;
 export type BulkDatabase2Config = {
-    triggerThrottleMs?: number;
+    maxTriggerThrottleMs?: number;
 };
 export declare class BulkDatabaseBase<T extends {
     key: string;

package/storage/BulkDatabase2/BulkDatabaseBase.ts

@@ -131,18 +131,18 @@ export type StorageFactory = (path: string) => Promise<FileStorage>;
 
 // Optional per-collection configuration.
 export type BulkDatabase2Config = {
-    // When set (> 0), the reactive change notifications writes/loads emit are throttled and BATCHED
-    // globally (across all keys), so a high-frequency write source doesn't re-run watchers on every single
-    // change. The throttle RAMPS like the write-flush one: the first change after a lull notifies
-    // immediately, then under sustained changes the delay doubles up to triggerThrottleMs, coalescing the
-    // burst into one notification. In-memory/async reads are always current — only the OBSERVABLE
-    // notification (the mobx re-render trigger) is delayed and merged.
-    triggerThrottleMs?: number;
+    // The MAXIMUM throttle (ms) for reactive change notifications; the actual delay RAMPS UP to it, it is
+    // never applied all at once. When set (> 0), the notifications writes/loads emit are batched globally
+    // (across all keys) so a high-frequency write source doesn't re-run watchers on every single change: a
+    // change after a lull notifies immediately, then under sustained changes the delay doubles up to this
+    // ceiling, coalescing the burst into one notification. In-memory/async reads are always current — only
+    // the OBSERVABLE notification (the mobx re-render trigger) is delayed and merged.
+    maxTriggerThrottleMs?: number;
 };
 
 // Trigger-throttle ramp: the first deferred notification waits this long, then the delay doubles on each
-// further change up to BulkDatabase2Config.triggerThrottleMs. ~16ms ≈ one animation frame, so an isolated
-// burst still notifies within a frame.
+// further change up to BulkDatabase2Config.maxTriggerThrottleMs. ~16ms ≈ one animation frame, so an
+// isolated burst still notifies within a frame.
 const TRIGGER_THROTTLE_FIRST_STEP_MS = 16;
 
 // The load/reset lifecycle shares one signal; every sync read observes it so it re-renders when the
@@ -310,7 +310,7 @@ export class BulkDatabaseBase<T extends { key: string }> {
     // the cache and may swap the reader) can never leave a stale entry behind.
     private dataGen = 0;
 
-    // ---- trigger throttle (see BulkDatabase2Config.triggerThrottleMs) ----
+    // ---- trigger throttle (see BulkDatabase2Config.maxTriggerThrottleMs) ----
     // Signals whose notification is deferred, the pending flush timer, and the ramping delay. Data state is
     // already updated synchronously; only these observable notifications are batched/delayed.
     private pendingSignals = new Set<string>();
@@ -363,14 +363,14 @@ export class BulkDatabaseBase<T extends { key: string }> {
         return this.readerKeys?.has(key) ?? false;
     }
 
-    // Notify observers of `signal`. With triggerThrottleMs set, notifications are batched and delayed on a
-    // ramping schedule so a high-frequency source can't re-run watchers on every change: a change after a
+    // Notify observers of `signal`. With maxTriggerThrottleMs set, notifications are batched and delayed on
+    // a ramping schedule so a high-frequency source can't re-run watchers on every change: a change after a
     // lull notifies on the next tick (no real delay, but all of one change's signals batch together);
     // under sustained changes the delay doubles up to the max, coalescing the burst into one notification.
     // Only the OBSERVABLE notification is delayed — the underlying data was already updated, so a read in
     // the meantime still sees current values.
     private invalidateSignal(signal: string) {
-        const maxMs = this.config.triggerThrottleMs ?? 0;
+        const maxMs = this.config.maxTriggerThrottleMs ?? 0;
         if (maxMs <= 0) { this.deps.invalidate(signal); return; }
         this.pendingSignals.add(signal);
         const now = Date.now();

package/storage/FileFolderAPI.d.ts

@@ -46,6 +46,7 @@ export type FileWrapper = {
         write(value: Buffer): Promise<void>;
         close(): Promise<void>;
     }>;
+    getURL?(): Promise<string>;
 };
 export type DirectoryWrapper = {
     readonly kind: "directory";
@@ -78,6 +79,7 @@ export declare class NodeJSFileHandleWrapper implements FileWrapper {
             arrayBuffer: () => Promise<ArrayBuffer>;
         };
     }>;
+    getURL(): Promise<string>;
     createWritable(config?: {
         keepExistingData?: boolean;
     }): Promise<{
@@ -142,5 +144,7 @@ export type FileStorage = IStorageRaw & {
     isRemote?: boolean;
 };
 export declare function wrapHandle(handle: DirectoryWrapper): FileStorage;
+export declare function getFileURL(file: FileWrapper): Promise<string>;
+export declare function disposeFileURL(url: string): void;
 export declare function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage>;
 export declare function tryToLoadPointer(pointer: string): Promise<DirectoryWrapper | undefined>;

package/storage/FileFolderAPI.tsx

@@ -56,6 +56,10 @@ export type FileWrapper = {
         write(value: Buffer): Promise<void>;
         close(): Promise<void>;
     }>;
+    // Returns a URL for the file's bytes, usable in <video>/<img>/fetch. Optional — the native browser
+    // FileSystemFileHandle has no such method, so prefer the getFileURL() helper, which falls back to a
+    // blob: URL via createObjectURL for native handles. Always release it with disposeFileURL when done.
+    getURL?(): Promise<string>;
 };
 export type DirectoryWrapper = {
     readonly kind: "directory";
@@ -261,6 +265,10 @@ export class NodeJSFileHandleWrapper implements FileWrapper {
         };
     }
 
+    async getURL() {
+        return "file://" + path.resolve(this.filePath);
+    }
+
     async createWritable(config?: { keepExistingData?: boolean }) {
         let fileHandle: fs.promises.FileHandle;
         const flags = config?.keepExistingData ? "r+" : "w";
@@ -715,6 +723,25 @@ export function wrapHandle(handle: DirectoryWrapper): FileStorage {
     };
 }
 
+// Returns a URL for a file's bytes, ready to drop into <video>/<img>/fetch. A native (local) file becomes
+// an in-memory blob: URL; a remote file becomes an https URL into the server's range-capable /media
+// endpoint (auth token in the query, since a media element can't send headers). Both support HTTP range /
+// seeking. ALWAYS hand the result to disposeFileURL when finished — for blob: URLs that frees memory.
+export async function getFileURL(file: FileWrapper): Promise<string> {
+    if (file.getURL) return file.getURL();
+    // Native FileSystemFileHandle (or any Blob-backed file): a blob: URL over the File itself.
+    const f = await file.getFile();
+    return URL.createObjectURL(f as unknown as Blob);
+}
+
+// Releases a URL from getFileURL. blob: URLs leak until the document is gone unless revoked; https/file:
+// URLs need no cleanup, so this is a no-op for them.
+export function disposeFileURL(url: string): void {
+    if (url.startsWith("blob:")) {
+        try { URL.revokeObjectURL(url); } catch { /* not in a browser, or already revoked */ }
+    }
+}
+
 // A StorageFactory backed by a remote server (path -> FileStorage), for code that injects its own
 // storage into BulkDatabase2 rather than going through the directory prompt.
 export function getRemoteFileStorageFactory(url: string, password: string, options?: RemoteOptions): (pathStr: string) => Promise<FileStorage> {

package/storage/remoteFileServer.ts

@@ -274,6 +274,40 @@ function formatBytes(n: number): string {
     return (n / 1024 / 1024 / 1024).toFixed(2) + "GB";
 }
 
+// Parse a single-range HTTP Range header ("bytes=start-end", "bytes=start-", "bytes=-suffix") into an
+// INCLUSIVE [start, end]. Returns "unsatisfiable" for a range past the file, or undefined for no/garbled
+// range (caller then serves the whole file). Only single ranges are supported (what media players use).
+function parseRange(header: string, size: number): { start: number; end: number } | "unsatisfiable" | undefined {
+    const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!m) return undefined;
+    const sRaw = m[1], eRaw = m[2];
+    if (sRaw === "" && eRaw === "") return undefined;
+    let start: number, end: number;
+    if (sRaw === "") {
+        const suffix = parseInt(eRaw, 10);
+        if (!suffix) return "unsatisfiable";
+        start = Math.max(0, size - suffix);
+        end = size - 1;
+    } else {
+        start = parseInt(sRaw, 10);
+        end = eRaw === "" ? size - 1 : parseInt(eRaw, 10);
+    }
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start >= size) return "unsatisfiable";
+    return { start, end: Math.min(end, size - 1) };
+}
+
+const MEDIA_TYPES: Record<string, string> = {
+    mp4: "video/mp4", m4v: "video/mp4", webm: "video/webm", mkv: "video/x-matroska", mov: "video/quicktime",
+    avi: "video/x-msvideo", ogv: "video/ogg", ts: "video/mp2t",
+    mp3: "audio/mpeg", m4a: "audio/mp4", aac: "audio/aac", flac: "audio/flac", wav: "audio/wav", ogg: "audio/ogg", opus: "audio/opus",
+    jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp", avif: "image/avif", svg: "image/svg+xml",
+    pdf: "application/pdf", txt: "text/plain; charset=utf-8", json: "application/json",
+};
+function mediaContentType(filePath: string): string {
+    const ext = filePath.slice(filePath.lastIndexOf(".") + 1).toLowerCase();
+    return MEDIA_TYPES[ext] || "application/octet-stream";
+}
+
 // Public (no-auth) landing page. The browser can't trust a self-signed cert from a background fetch, so
 // the user opens this URL once, accepts the browser's security warning, and the cert becomes trusted for
 // the origin — then the app's fetches work. This page is what they see after accepting.
@@ -336,8 +370,9 @@ export function startRemoteFileServer(options: RemoteFileServerOptions): Promise
         const origin = (req.headers["origin"] as string) || "*";
         const cors: Record<string, string> = {
             "Access-Control-Allow-Origin": origin,
-            "Access-Control-Allow-Methods": "GET, PUT, POST, DELETE, OPTIONS",
-            "Access-Control-Allow-Headers": "authorization, content-type",
+            "Access-Control-Allow-Methods": "GET, HEAD, PUT, POST, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "authorization, content-type, range",
+            "Access-Control-Expose-Headers": "content-range, accept-ranges, content-length",
             "Access-Control-Max-Age": "86400",
             "Vary": "Origin",
         };
@@ -359,7 +394,8 @@ export function startRemoteFileServer(options: RemoteFileServerOptions): Promise
             }
 
             const auth = (req.headers["authorization"] as string) || "";
-            const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+            // Bearer header for API clients; ?token= query for media URLs (a <video> element can't set headers).
+            const token = (auth.startsWith("Bearer ") ? auth.slice(7) : "") || url.searchParams.get("token") || "";
             if (!timingSafeEqualStr(normalizePassword(token), normPassword)) return sendJson(401, { error: "unauthorized" });
 
             const relPath = url.searchParams.get("path") || "";
@@ -391,6 +427,33 @@ export function startRemoteFileServer(options: RemoteFileServerOptions): Promise
                 fs.createReadStream(full, { start, end: end - 1 }).on("error", () => res.end()).pipe(res);
                 return;
             }
+            // Range-capable media endpoint for <video>/<img>/fetch: honors the Range header (206 +
+            // Content-Range + Accept-Ranges) so seeking works. Auth came from the ?token= query above.
+            if ((req.method === "GET" || req.method === "HEAD") && op === "/media") {
+                let st: fs.Stats;
+                try { st = fs.statSync(full); } catch { return sendJson(404, { error: "not found" }); }
+                if (st.isDirectory()) return sendJson(400, { error: "is a directory" });
+                const rangeHeader = req.headers["range"] as string | undefined;
+                const range = rangeHeader ? parseRange(rangeHeader, st.size) : undefined;
+                if (range === "unsatisfiable") {
+                    res.writeHead(416, Object.assign({}, cors, { "Content-Range": `bytes */${st.size}`, "Accept-Ranges": "bytes" }));
+                    return res.end();
+                }
+                const start = range ? range.start : 0;
+                const end = range ? range.end : st.size - 1; // inclusive
+                const length = st.size === 0 ? 0 : end - start + 1;
+                const headers: Record<string, string> = Object.assign({}, cors, {
+                    "Content-Type": mediaContentType(full),
+                    "Accept-Ranges": "bytes",
+                    "Content-Length": String(length),
+                });
+                if (range) headers["Content-Range"] = `bytes ${start}-${end}/${st.size}`;
+                res.writeHead(range ? 206 : 200, headers);
+                if (req.method === "HEAD" || length === 0) return res.end();
+                recordAccess(clientIp(req), "read", relPath, length);
+                fs.createReadStream(full, { start, end }).on("error", () => res.end()).pipe(res);
+                return;
+            }
             if ((req.method === "PUT" || req.method === "POST") && (op === "/append" || op === "/set")) {
                 const body = await readBody(req);
                 fs.mkdirSync(path.dirname(full), { recursive: true });

package/storage/remoteFileStorage.ts

@@ -358,6 +358,11 @@ class RemoteFileWrapper implements FileWrapper {
             },
         };
     }
+    async getURL() {
+        // HTTPS URL into the server's range-capable /media endpoint. The token rides in the query because a
+        // <video>/<img> element can't send an Authorization header.
+        return `${this.conn.url}/media?path=${encodeURIComponent(this.filePath)}&token=${encodeURIComponent(this.conn.password)}`;
+    }
     async createWritable(config?: { keepExistingData?: boolean }) {
         const conn = this.conn, filePath = this.filePath, append = !!config?.keepExistingData;
         const chunks: Buffer[] = [];