@velajs/storage 0.3.1 → 0.3.2

package/dist/http/protocol.types.d.ts

@@ -1,76 +0,0 @@
-import type { SignedUpload, UploadResult, UploadedPart } from '../storage.types';
-export interface SignUploadRequest {
-    key: string;
-    contentType?: string;
-    size?: number;
-    metadata?: Record<string, string>;
-    expiresIn?: number;
-}
-export interface MultipartCreateRequest {
-    key: string;
-    contentType?: string;
-    metadata?: Record<string, string>;
-    partSize?: number;
-}
-export interface SignPartRequest {
-    key: string;
-    uploadId: string;
-    partNumber: number;
-}
-export interface MultipartCompleteRequest {
-    key: string;
-    uploadId: string;
-    parts: UploadedPart[];
-}
-export interface MultipartAbortRequest {
-    key: string;
-    uploadId: string;
-}
-export interface DeleteRequest {
-    keys: string[];
-}
-export interface SignUploadResponse {
-    key: string;
-    upload: SignedUpload;
-}
-export interface MultipartCreateResponse {
-    key: string;
-    uploadId: string;
-    partSize: number;
-}
-export interface SignPartResponse {
-    partNumber: number;
-    method: 'PUT';
-    url: string;
-    headers?: Record<string, string>;
-}
-export type MultipartCompleteResponse = UploadResult;
-export interface OkResponse {
-    ok: true;
-}
-/** JSON-safe {@link StoredFile} projection (no body accessors). */
-export interface StoredFileMeta {
-    key: string;
-    name: string;
-    size: number;
-    type: string;
-    lastModified?: number;
-    etag?: string;
-    metadata?: Record<string, string>;
-}
-export interface ListResponse {
-    items: StoredFileMeta[];
-    prefixes?: string[];
-    cursor?: string;
-}
-export interface SignDownloadResponse {
-    url: string;
-    expiresAt: number;
-}
-export type StorageWireErrorCode = 'forbidden' | 'invalid_key' | 'invalid_request' | 'not_found' | 'conflict' | 'rate_limited' | 'capability_unsupported' | 'upstream_error';
-export interface StorageErrorBody {
-    error: {
-        code: StorageWireErrorCode;
-        message: string;
-    };
-}

package/dist/http/protocol.types.js

@@ -1 +0,0 @@
-export { };

package/dist/internal/body.d.ts

@@ -1,18 +0,0 @@
-import type { Body } from '../storage.types';
-/** Byte length when known synchronously; `undefined` for unknown-length streams. */
-export declare function byteLengthOf(body: Body): number | undefined;
-/** True for the unknown-length stream case. */
-export declare function isStream(body: Body): body is ReadableStream<Uint8Array>;
-/** Buffer any body into bytes (used for hashing / part chunking). */
-export declare function toBytes(body: Body): Promise<Uint8Array>;
-/** View any body as a byte stream without buffering when it already is one. */
-export declare function toStream(body: Body): ReadableStream<Uint8Array>;
-/** Wrap a stream so `onLoaded` is called with the cumulative byte count. */
-export declare function countingStream(src: ReadableStream<Uint8Array>, onLoaded: (loaded: number) => void): ReadableStream<Uint8Array>;
-/** Concatenate ordered byte chunks into one buffer. */
-export declare function concatChunks(chunks: Uint8Array[]): Uint8Array;
-/**
- * Yield fixed-size (`partSize`) chunks from a byte stream, buffering only one
- * part at a time. The final chunk may be smaller. Empty input yields nothing.
- */
-export declare function chunkStream(src: ReadableStream<Uint8Array>, partSize: number): AsyncGenerator<Uint8Array>;

package/dist/internal/body.js

@@ -1,90 +0,0 @@
-const encoder = new TextEncoder();
-/** Byte length when known synchronously; `undefined` for unknown-length streams. */ export function byteLengthOf(body) {
-    if (typeof body === 'string') return encoder.encode(body).byteLength;
-    if (body instanceof Blob) return body.size; // File extends Blob
-    if (body instanceof ArrayBuffer) return body.byteLength;
-    if (ArrayBuffer.isView(body)) return body.byteLength;
-    return undefined; // ReadableStream
-}
-/** True for the unknown-length stream case. */ export function isStream(body) {
-    return body instanceof ReadableStream;
-}
-/** Buffer any body into bytes (used for hashing / part chunking). */ export async function toBytes(body) {
-    if (typeof body === 'string') return encoder.encode(body);
-    if (body instanceof Uint8Array) return body;
-    if (body instanceof ArrayBuffer) return new Uint8Array(body);
-    if (ArrayBuffer.isView(body)) {
-        // Copy into a fresh ArrayBuffer-backed view (the source buffer is
-        // ArrayBufferLike, which may be a SharedArrayBuffer).
-        const slice = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
-        return new Uint8Array(slice);
-    }
-    if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer());
-    return new Uint8Array(await new Response(body).arrayBuffer()); // ReadableStream
-}
-/** View any body as a byte stream without buffering when it already is one. */ export function toStream(body) {
-    if (body instanceof ReadableStream) return body;
-    const res = new Response(body);
-    return res.body ?? emptyStream();
-}
-function emptyStream() {
-    return new ReadableStream({
-        start (controller) {
-            controller.close();
-        }
-    });
-}
-/** Wrap a stream so `onLoaded` is called with the cumulative byte count. */ export function countingStream(src, onLoaded) {
-    let loaded = 0;
-    const reader = src.getReader();
-    return new ReadableStream({
-        async pull (controller) {
-            const { done, value } = await reader.read();
-            if (done) {
-                controller.close();
-                return;
-            }
-            loaded += value.byteLength;
-            onLoaded(loaded);
-            controller.enqueue(value);
-        },
-        cancel (reason) {
-            return reader.cancel(reason);
-        }
-    });
-}
-/** Concatenate ordered byte chunks into one buffer. */ export function concatChunks(chunks) {
-    let total = 0;
-    for (const c of chunks)total += c.byteLength;
-    const out = new Uint8Array(total);
-    let offset = 0;
-    for (const c of chunks){
-        out.set(c, offset);
-        offset += c.byteLength;
-    }
-    return out;
-}
-/**
- * Yield fixed-size (`partSize`) chunks from a byte stream, buffering only one
- * part at a time. The final chunk may be smaller. Empty input yields nothing.
- */ export async function* chunkStream(src, partSize) {
-    const reader = src.getReader();
-    let buffer = new Uint8Array(0);
-    try {
-        for(;;){
-            const { done, value } = await reader.read();
-            if (done) break;
-            buffer = buffer.length === 0 ? value : concatChunks([
-                buffer,
-                value
-            ]);
-            while(buffer.byteLength >= partSize){
-                yield buffer.subarray(0, partSize);
-                buffer = buffer.subarray(partSize);
-            }
-        }
-        if (buffer.byteLength > 0) yield buffer;
-    } finally{
-        reader.releaseLock();
-    }
-}

package/dist/internal/retry.d.ts

@@ -1,41 +0,0 @@
-import { StorageError } from '../storage.error';
-import type { RetryOptions } from '../storage.types';
-/**
- * Combine multiple abort signals into one. The result aborts as soon as any
- * input aborts, adopting that input's reason. Listeners are cleaned up on
- * first abort. `undefined` inputs are ignored.
- */
-export declare function anySignal(signals: Array<AbortSignal | undefined>): AbortSignal;
-/** A controller that aborts after `ms`; call `clear()` to cancel the timer. */
-export declare function timeoutController(ms: number): {
-    controller: AbortController;
-    clear: () => void;
-};
-/** Resolve after `ms`, or reject with `Aborted` if `signal` fires first. */
-export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
-export interface NormalizedRetry {
-    max: number;
-    backoff: (ctx: {
-        attempt: number;
-        error: StorageError;
-    }) => number;
-}
-export declare function normalizeRetry(retries: RetryOptions | undefined): NormalizedRetry;
-export interface RunOptions {
-    retries?: RetryOptions;
-    timeout?: number;
-    signal?: AbortSignal;
-}
-/**
- * Run `fn` with per-attempt timeout, caller-abort propagation, and
- * retryable-error backoff. `fn` receives the combined per-attempt signal.
- *
- * - Caller-abort (`opts.signal`) → `Aborted`, never retried.
- * - Per-attempt timeout → `Timeout` (retryable by default, within budget).
- * - Only errors with `error.retryable` are retried, up to `retries.max`.
- */
-export declare function runWithRetry<T>(fn: (signal: AbortSignal | undefined) => Promise<T>, opts: RunOptions, onRetry?: (info: {
-    attempt: number;
-    delayMs: number;
-    error: StorageError;
-}) => void): Promise<T>;

package/dist/internal/retry.js

@@ -1,127 +0,0 @@
-import { StorageError, isAbort } from "../storage.error.js";
-// Retry/timeout/abort plumbing. Deliberately does NOT use `AbortSignal.any`
-// (only added in Node 20.3 — `engines.node >= 20` allows 20.0–20.2) nor
-// `AbortSignal.timeout`; both are re-implemented from `AbortController` +
-// `setTimeout` so the package runs on every target from 20.0 up.
-/**
- * Combine multiple abort signals into one. The result aborts as soon as any
- * input aborts, adopting that input's reason. Listeners are cleaned up on
- * first abort. `undefined` inputs are ignored.
- */ export function anySignal(signals) {
-    const controller = new AbortController();
-    const live = signals.filter((s)=>s != null);
-    const onAbort = (reason)=>{
-        cleanup();
-        if (!controller.signal.aborted) controller.abort(reason);
-    };
-    const cleanup = ()=>{
-        for (const s of live)s.removeEventListener('abort', handlers.get(s));
-    };
-    const handlers = new Map();
-    for (const s of live){
-        if (s.aborted) {
-            controller.abort(s.reason);
-            return controller.signal;
-        }
-        const h = ()=>onAbort(s.reason);
-        handlers.set(s, h);
-        s.addEventListener('abort', h, {
-            once: true
-        });
-    }
-    return controller.signal;
-}
-/** A controller that aborts after `ms`; call `clear()` to cancel the timer. */ export function timeoutController(ms) {
-    const controller = new AbortController();
-    const timer = setTimeout(()=>{
-        controller.abort(new StorageError('Timeout', `operation timed out after ${ms}ms`));
-    }, ms);
-    return {
-        controller,
-        clear: ()=>clearTimeout(timer)
-    };
-}
-/** Resolve after `ms`, or reject with `Aborted` if `signal` fires first. */ export function sleep(ms, signal) {
-    return new Promise((resolve, reject)=>{
-        if (signal?.aborted) {
-            reject(new StorageError('Aborted', 'operation aborted'));
-            return;
-        }
-        const timer = setTimeout(()=>{
-            signal?.removeEventListener('abort', onAbort);
-            resolve();
-        }, ms);
-        const onAbort = ()=>{
-            clearTimeout(timer);
-            reject(new StorageError('Aborted', 'operation aborted'));
-        };
-        signal?.addEventListener('abort', onAbort, {
-            once: true
-        });
-    });
-}
-const DEFAULT_BASE_MS = 100;
-const DEFAULT_CAP_MS = 2000;
-function defaultBackoff({ attempt }) {
-    const expo = Math.min(DEFAULT_CAP_MS, DEFAULT_BASE_MS * 2 ** (attempt - 1));
-    return expo + Math.floor(Math.random() * DEFAULT_BASE_MS); // full-ish jitter
-}
-export function normalizeRetry(retries) {
-    if (retries == null) return {
-        max: 0,
-        backoff: defaultBackoff
-    };
-    if (typeof retries === 'number') return {
-        max: Math.max(0, retries),
-        backoff: defaultBackoff
-    };
-    return {
-        max: Math.max(0, retries.max),
-        backoff: retries.backoff ?? defaultBackoff
-    };
-}
-/**
- * Run `fn` with per-attempt timeout, caller-abort propagation, and
- * retryable-error backoff. `fn` receives the combined per-attempt signal.
- *
- * - Caller-abort (`opts.signal`) → `Aborted`, never retried.
- * - Per-attempt timeout → `Timeout` (retryable by default, within budget).
- * - Only errors with `error.retryable` are retried, up to `retries.max`.
- */ export async function runWithRetry(fn, opts, onRetry) {
-    const { max, backoff } = normalizeRetry(opts.retries);
-    const useTimeout = typeof opts.timeout === 'number' && opts.timeout > 0;
-    let attempt = 0;
-    for(;;){
-        if (opts.signal?.aborted) throw new StorageError('Aborted', 'operation aborted');
-        const to = useTimeout ? timeoutController(opts.timeout) : undefined;
-        const signal = to ? anySignal([
-            opts.signal,
-            to.controller.signal
-        ]) : opts.signal;
-        try {
-            return await fn(signal);
-        } catch (e) {
-            // Hard caller cancellation: never retried.
-            if (opts.signal?.aborted) throw new StorageError('Aborted', 'operation aborted', {
-                cause: e
-            });
-            const error = to?.controller.signal.aborted && isAbort(e) ? new StorageError('Timeout', `operation timed out after ${opts.timeout}ms`, {
-                cause: e
-            }) : StorageError.wrap(e);
-            if (attempt >= max || !error.retryable) throw error;
-            attempt += 1;
-            const delayMs = Math.max(0, backoff({
-                attempt,
-                error
-            }));
-            onRetry?.({
-                attempt,
-                delayMs,
-                error
-            });
-            await sleep(delayMs, opts.signal);
-        } finally{
-            to?.clear();
-        }
-    }
-}

package/dist/internal/stored-file.d.ts

@@ -1,27 +0,0 @@
-import type { StoredFile } from '../storage.types';
-export interface StoredFileMeta {
-    key: string;
-    name?: string;
-    size: number;
-    type?: string;
-    lastModified?: number;
-    etag?: string;
-    metadata?: Record<string, string>;
-}
-/**
- * Where a {@link StoredFile}'s bytes come from:
- * - `bytes`  — already in memory (memory driver, buffered reads).
- * - `stream` — a single-use byte stream (a live download response body).
- * - `lazy`   — a thunk that issues the GET on first body access (head()).
- */
-export type StoredFileSource = {
-    kind: 'bytes';
-    bytes: Uint8Array;
-} | {
-    kind: 'stream';
-    stream: ReadableStream<Uint8Array>;
-} | {
-    kind: 'lazy';
-    fetch: () => Promise<Response>;
-};
-export declare function createStoredFile(meta: StoredFileMeta, source: StoredFileSource): StoredFile;

package/dist/internal/stored-file.js

@@ -1,114 +0,0 @@
-import { StorageError } from "../storage.error.js";
-function nameFromKey(key) {
-    const i = key.lastIndexOf('/');
-    return i === -1 ? key : key.slice(i + 1);
-}
-function bytesToStream(bytes) {
-    return new ReadableStream({
-        start (controller) {
-            controller.enqueue(bytes);
-            controller.close();
-        }
-    });
-}
-function toArrayBuffer(bytes) {
-    const ab = new ArrayBuffer(bytes.byteLength);
-    new Uint8Array(ab).set(bytes);
-    return ab;
-}
-let StoredFileImpl = class StoredFileImpl {
-    key;
-    name;
-    size;
-    type;
-    lastModified;
-    etag;
-    metadata;
-    #source;
-    #bytes;
-    #streamTaken = false;
-    constructor(meta, source){
-        this.key = meta.key;
-        this.name = meta.name ?? nameFromKey(meta.key);
-        this.size = meta.size;
-        this.type = meta.type ?? 'application/octet-stream';
-        this.lastModified = meta.lastModified;
-        this.etag = meta.etag;
-        this.metadata = meta.metadata;
-        this.#source = source;
-        if (source.kind === 'bytes') this.#bytes = source.bytes;
-    }
-    async #buffer() {
-        if (this.#bytes) return this.#bytes;
-        const s = this.#source;
-        if (s.kind === 'bytes') {
-            this.#bytes = s.bytes;
-            return this.#bytes;
-        }
-        if (s.kind === 'stream') {
-            if (this.#streamTaken) {
-                throw new StorageError('Provider', `body of ${this.key} already consumed`);
-            }
-            this.#streamTaken = true;
-            this.#bytes = new Uint8Array(await new Response(s.stream).arrayBuffer());
-            return this.#bytes;
-        }
-        // s.kind === 'lazy'
-        const res = await s.fetch();
-        if (!res.ok) throw StorageError.fromStatus(res.status, `download failed: ${this.key}`);
-        this.#bytes = new Uint8Array(await res.arrayBuffer());
-        return this.#bytes;
-    }
-    async arrayBuffer() {
-        return toArrayBuffer(await this.#buffer());
-    }
-    async text() {
-        return new TextDecoder().decode(await this.#buffer());
-    }
-    async blob() {
-        const b = await this.#buffer();
-        return new Blob([
-            toArrayBuffer(b)
-        ], {
-            type: this.type
-        });
-    }
-    stream() {
-        if (this.#bytes) return bytesToStream(this.#bytes);
-        const s = this.#source;
-        if (s.kind === 'bytes') return bytesToStream(s.bytes);
-        if (s.kind === 'stream') {
-            if (this.#streamTaken) {
-                throw new StorageError('Provider', `body of ${this.key} already consumed`);
-            }
-            this.#streamTaken = true;
-            return s.stream;
-        }
-        // lazy: fetch on first pull
-        let reader;
-        const fetchFn = s.fetch;
-        const key = this.key;
-        return new ReadableStream({
-            async pull (controller) {
-                let r = reader;
-                if (!r) {
-                    const res = await fetchFn();
-                    if (!res.ok || !res.body) {
-                        throw StorageError.fromStatus(res.status, `download failed: ${key}`);
-                    }
-                    r = res.body.getReader();
-                    reader = r;
-                }
-                const { done, value } = await r.read();
-                if (done) controller.close();
-                else controller.enqueue(value);
-            },
-            cancel (reason) {
-                return reader?.cancel(reason);
-            }
-        });
-    }
-};
-export function createStoredFile(meta, source) {
-    return new StoredFileImpl(meta, source);
-}

package/dist/middleware/cache.d.ts

@@ -1,50 +0,0 @@
-import { type Middleware } from './wrap';
-export interface CachedMeta {
-    key: string;
-    name: string;
-    size: number;
-    type: string;
-    lastModified?: number;
-    etag?: string;
-    metadata?: Record<string, string>;
-}
-export interface CacheEntry {
-    expiresAt: number;
-    kind: 'meta' | 'exists';
-    meta?: CachedMeta;
-    exists?: boolean;
-}
-type MaybePromise<T> = T | Promise<T>;
-export interface CacheStore {
-    get(key: string): MaybePromise<CacheEntry | undefined>;
-    set(key: string, value: CacheEntry, ttlMs: number): MaybePromise<void>;
-    delete(key: string): MaybePromise<void>;
-}
-/** In-memory, per-isolate cache with lazy TTL + insertion-order eviction (no timers). */
-export declare class MapCacheStore implements CacheStore {
-    #private;
-    private readonly maxEntries;
-    private readonly now;
-    constructor(maxEntries?: number, now?: () => number);
-    get(key: string): CacheEntry | undefined;
-    set(key: string, value: CacheEntry): void;
-    delete(key: string): void;
-}
-export interface CacheOptions {
-    store?: CacheStore;
-    ttlMs?: number;
-    /** Which reads to cache. Default: head + exists (body/list are not cached). */
-    cache?: {
-        head?: boolean;
-        exists?: boolean;
-    };
-    keyPrefix?: string;
-    now?: () => number;
-}
-/**
- * Read-through cache for `head` / `exists`. Bodies are never cached (a `head`
- * hit still lazily fetches on body access), and `list` is not cached
- * (cross-prefix invalidation is intractable). Writes invalidate the key.
- */
-export declare function cache(opts?: CacheOptions): Middleware;
-export {};

package/dist/middleware/cache.js

@@ -1,101 +0,0 @@
-import { createStoredFile } from "../internal/stored-file.js";
-import { passthrough } from "./wrap.js";
-/** In-memory, per-isolate cache with lazy TTL + insertion-order eviction (no timers). */ export class MapCacheStore {
-    maxEntries;
-    now;
-    #map = new Map();
-    constructor(maxEntries = 1000, now = Date.now){
-        this.maxEntries = maxEntries;
-        this.now = now;
-    }
-    get(key) {
-        const e = this.#map.get(key);
-        if (!e) return undefined;
-        if (e.expiresAt <= this.now()) {
-            this.#map.delete(key);
-            return undefined;
-        }
-        return e;
-    }
-    set(key, value) {
-        this.#map.delete(key);
-        this.#map.set(key, value);
-        if (this.#map.size > this.maxEntries) {
-            const oldest = this.#map.keys().next().value;
-            if (oldest !== undefined) this.#map.delete(oldest);
-        }
-    }
-    delete(key) {
-        this.#map.delete(key);
-    }
-}
-function toMeta(f) {
-    return {
-        key: f.key,
-        name: f.name,
-        size: f.size,
-        type: f.type,
-        lastModified: f.lastModified,
-        etag: f.etag,
-        metadata: f.metadata
-    };
-}
-/**
- * Read-through cache for `head` / `exists`. Bodies are never cached (a `head`
- * hit still lazily fetches on body access), and `list` is not cached
- * (cross-prefix invalidation is intractable). Writes invalidate the key.
- */ export function cache(opts = {}) {
-    const now = opts.now ?? Date.now;
-    const store = opts.store ?? new MapCacheStore(1000, now);
-    const ttl = opts.ttlMs ?? 60_000;
-    const doHead = opts.cache?.head ?? true;
-    const doExists = opts.cache?.exists ?? true;
-    const ns = (k)=>`${opts.keyPrefix ?? ''}${k}`;
-    return (inner)=>{
-        const invalidate = async (...keys)=>{
-            await Promise.all(keys.map((k)=>store.delete(ns(k))));
-        };
-        return passthrough(inner, {
-            head: doHead ? async (k, o)=>{
-                const hit = await store.get(ns(k));
-                if (hit?.kind === 'meta' && hit.meta) {
-                    return createStoredFile(hit.meta, {
-                        kind: 'lazy',
-                        fetch: async ()=>new Response((await inner.download(k)).stream())
-                    });
-                }
-                const file = await inner.head(k, o);
-                await store.set(ns(k), {
-                    kind: 'meta',
-                    meta: toMeta(file),
-                    expiresAt: now() + ttl
-                }, ttl);
-                return file;
-            } : undefined,
-            exists: doExists ? async (k, o)=>{
-                const hit = await store.get(ns(k));
-                if (hit?.kind === 'exists' && typeof hit.exists === 'boolean') return hit.exists;
-                const exists = await inner.exists(k, o);
-                await store.set(ns(k), {
-                    kind: 'exists',
-                    exists,
-                    expiresAt: now() + ttl
-                }, ttl);
-                return exists;
-            } : undefined,
-            upload: async (k, b, o)=>{
-                const r = await inner.upload(k, b, o);
-                await invalidate(k);
-                return r;
-            },
-            delete: async (k, o)=>{
-                await inner.delete(k, o);
-                await invalidate(k);
-            },
-            copy: async (f, t, o)=>{
-                await inner.copy(f, t, o);
-                await invalidate(t);
-            }
-        });
-    };
-}

package/dist/middleware/compose.d.ts

@@ -1,12 +0,0 @@
-import type { StorageDriver } from '../storage.types';
-import type { Middleware } from './wrap';
-/**
- * Compose middlewares over a base driver. Listed innermost → outermost:
- * `compose(base, a, b, c)` yields `c(b(a(base)))`, so on any call `c` runs
- * first (outermost) and `base` last. The same wrapper handles read and write,
- * so the reverse order on download comes for free.
- *
- * There is deliberately NO default preset — each middleware is opt-in, so you
- * never accidentally ship, e.g., compress-then-encrypt (a CRIME/BREACH vector).
- */
-export declare function compose(base: StorageDriver, ...middlewares: Middleware[]): StorageDriver;

package/dist/middleware/compose.js

@@ -1,11 +0,0 @@
-/**
- * Compose middlewares over a base driver. Listed innermost → outermost:
- * `compose(base, a, b, c)` yields `c(b(a(base)))`, so on any call `c` runs
- * first (outermost) and `base` last. The same wrapper handles read and write,
- * so the reverse order on download comes for free.
- *
- * There is deliberately NO default preset — each middleware is opt-in, so you
- * never accidentally ship, e.g., compress-then-encrypt (a CRIME/BREACH vector).
- */ export function compose(base, ...middlewares) {
-    return middlewares.reduce((driver, wrap)=>wrap(driver), base);
-}