@velajs/storage 0.3.0 → 0.3.2

package/dist/storage.facade.js

@@ -1,443 +0,0 @@
-import { byteLengthOf, chunkStream, countingStream, isStream, toStream } from "./internal/body.js";
-import { normalizeRetry, runWithRetry } from "./internal/retry.js";
-import { joinKey, normalizePrefix, sanitizeKey, stripPrefix } from "./object-key.js";
-import { StorageError } from "./storage.error.js";
-const DEFAULT_PART_SIZE = 5 * 1024 * 1024; // 5 MiB (S3 minimum non-final part)
-const DEFAULT_CONCURRENCY = 4;
-// Known-length bodies larger than this are routed through multipart so we never
-// buffer a whole large object in memory (aws4fetch must hash the payload).
-const MULTIPART_THRESHOLD = 16 * 1024 * 1024;
-/**
- * The consumer-facing storage handle. Wraps a {@link StorageDriver} with
- * capability-gating (throws before any driver call), retry/timeout/abort,
- * prefix scoping, generic `move`/`deleteMany` fallbacks, multipart
- * orchestration, progress synthesis, and observability hooks.
- *
- * Framework-free — `StorageService` builds and caches one of these per bucket.
- */ export class Storage {
-    #driver;
-    #prefix;
-    #readonly;
-    #opts;
-    constructor(opts){
-        this.#opts = opts;
-        this.#driver = opts.driver;
-        this.#prefix = normalizePrefix(opts.prefix);
-        this.#readonly = opts.readonly ?? false;
-    }
-    get raw() {
-        return this.#driver.raw;
-    }
-    get driver() {
-        return this.#driver;
-    }
-    get capabilities() {
-        const d = this.#driver;
-        return {
-            rangeRead: !!d.supportsRange,
-            uploadProgress: !!d.reportsUploadProgress,
-            delimiter: !!d.supportsDelimiter,
-            metadata: !!d.supportsMetadata,
-            cacheControl: !!d.supportsCacheControl,
-            serverSideCopy: !!d.supportsServerSideCopy,
-            multipart: typeof d.createMultipartUpload === 'function',
-            signedMultipart: d.signedMultipart != null,
-            signedUrl: d.signedUrl ?? {
-                supported: false,
-                upload: false
-            }
-        };
-    }
-    // ---- upload ------------------------------------------------------------
-    async upload(key, body, opts) {
-        this.#assertWritable();
-        this.#assertUploadSupported(opts);
-        const d = this.#driver;
-        const path = this.#path(key);
-        const len = byteLengthOf(body);
-        const wantsMultipart = opts?.multipart != null && opts.multipart !== false;
-        const unknownStream = isStream(body) && len === undefined;
-        const bigKnown = len != null && len > MULTIPART_THRESHOLD;
-        const canMultipart = typeof d.createMultipartUpload === 'function';
-        if (wantsMultipart && !canMultipart) {
-            throw new StorageError('Unsupported', `${d.name}: multipart not supported`);
-        }
-        if ((wantsMultipart || unknownStream || bigKnown) && canMultipart) {
-            const result = await this.#exec('upload', key, false, opts, ()=>this.#putMultipart(path, body, opts));
-            return {
-                ...result,
-                key
-            };
-        }
-        const streaming = isStream(body);
-        let outBody = body;
-        if (opts?.onProgress && !d.reportsUploadProgress && streaming) {
-            outBody = countingStream(body, (loaded)=>opts.onProgress({
-                    loaded,
-                    total: len
-                }));
-        }
-        const result = await this.#exec('upload', key, !streaming, opts, (signal)=>d.upload(path, outBody, {
-                ...opts,
-                signal
-            }));
-        if (opts?.onProgress && !d.reportsUploadProgress && !streaming && len != null) {
-            opts.onProgress({
-                loaded: len,
-                total: len
-            });
-        }
-        return {
-            ...result,
-            key
-        };
-    }
-    async #putMultipart(path, body, opts) {
-        const mp = typeof opts?.multipart === 'object' ? opts.multipart : {};
-        const partSize = mp.partSize ?? DEFAULT_PART_SIZE;
-        const concurrency = Math.max(1, mp.concurrency ?? DEFAULT_CONCURRENCY);
-        const total = byteLengthOf(body);
-        const upload = await this.#driver.createMultipartUpload(path, {
-            contentType: opts?.contentType,
-            cacheControl: opts?.cacheControl,
-            metadata: opts?.metadata,
-            signal: opts?.signal
-        });
-        try {
-            const parts = [];
-            let uploadedBytes = 0;
-            let partNumber = 0;
-            const inflight = new Set();
-            for await (const chunk of chunkStream(toStream(body), partSize)){
-                partNumber += 1;
-                const n = partNumber;
-                const size = chunk.byteLength;
-                const task = (async ()=>{
-                    const up = await upload.uploadPart(n, chunk, {
-                        signal: opts?.signal
-                    });
-                    parts[n - 1] = {
-                        partNumber: n,
-                        etag: up.etag,
-                        size: up.size ?? size
-                    };
-                    uploadedBytes += size;
-                    opts?.onProgress?.({
-                        loaded: uploadedBytes,
-                        total
-                    });
-                })();
-                const tracked = task.finally(()=>inflight.delete(tracked));
-                inflight.add(tracked);
-                if (inflight.size >= concurrency) await Promise.race(inflight);
-            }
-            await Promise.all(inflight);
-            return await upload.complete(parts, {
-                signal: opts?.signal
-            });
-        } catch (e) {
-            await upload.abort().catch(()=>{});
-            throw StorageError.wrap(e);
-        }
-    }
-    // ---- read / metadata ---------------------------------------------------
-    async download(key, opts) {
-        if (opts?.range) this.#assertRange();
-        const file = await this.#exec('download', key, true, opts, (signal)=>this.#driver.download(this.#path(key), {
-                ...opts,
-                signal
-            }));
-        return this.#relabel(file, key);
-    }
-    async head(key, opts) {
-        const file = await this.#exec('head', key, true, opts, (signal)=>this.#driver.head(this.#path(key), {
-                ...opts,
-                signal
-            }));
-        return this.#relabel(file, key);
-    }
-    exists(key, opts) {
-        return this.#exec('exists', key, true, opts, (signal)=>this.#driver.exists(this.#path(key), {
-                ...opts,
-                signal
-            }));
-    }
-    async delete(keyOrKeys, opts) {
-        this.#assertWritable();
-        if (Array.isArray(keyOrKeys)) return this.#deleteMany(keyOrKeys, opts);
-        const key = keyOrKeys;
-        return this.#exec('delete', key, true, opts, (signal)=>this.#driver.delete(this.#path(key), {
-                ...opts,
-                signal
-            }));
-    }
-    async #deleteMany(keys, opts) {
-        const d = this.#driver;
-        if (d.deleteMany) {
-            const res = await this.#exec('deleteMany', undefined, true, opts, (signal)=>d.deleteMany(keys.map((k)=>this.#path(k)), {
-                    ...opts,
-                    signal
-                }));
-            return {
-                deleted: res.deleted.map((k)=>this.#strip(k)),
-                errors: res.errors?.map((e)=>({
-                        key: this.#strip(e.key),
-                        error: e.error
-                    }))
-            };
-        }
-        // Generic bounded fan-out fallback.
-        const concurrency = Math.max(1, opts?.concurrency ?? 8);
-        const stopOnError = opts?.stopOnError ?? false;
-        const deleted = [];
-        const errors = [];
-        let index = 0;
-        let stopped = false;
-        const worker = async ()=>{
-            while(index < keys.length && !stopped){
-                const key = keys[index++];
-                try {
-                    await d.delete(this.#path(key), {
-                        signal: opts?.signal
-                    });
-                    deleted.push(key);
-                } catch (e) {
-                    const error = StorageError.wrap(e);
-                    errors.push({
-                        key,
-                        error
-                    });
-                    if (stopOnError) {
-                        stopped = true;
-                        throw error;
-                    }
-                }
-            }
-        };
-        const runners = Array.from({
-            length: Math.min(concurrency, keys.length)
-        }, worker);
-        if (stopOnError) await Promise.all(runners);
-        else await Promise.allSettled(runners);
-        return {
-            deleted,
-            errors: errors.length ? errors : undefined
-        };
-    }
-    async copy(from, to, opts) {
-        this.#assertWritable();
-        return this.#exec('copy', to, true, opts, (signal)=>this.#driver.copy(this.#path(from), this.#path(to), {
-                ...opts,
-                signal
-            }));
-    }
-    async move(from, to, opts) {
-        this.#assertWritable();
-        const f = this.#path(from);
-        const t = this.#path(to);
-        if (f === t) return;
-        if (this.#driver.move) {
-            await this.#exec('move', to, true, opts, (signal)=>this.#driver.move(f, t, {
-                    ...opts,
-                    signal
-                }));
-            return;
-        }
-        await this.#exec('move', to, true, opts, async (signal)=>{
-            await this.#driver.copy(f, t, {
-                ...opts,
-                signal
-            });
-            await this.#driver.delete(f, {
-                ...opts,
-                signal
-            });
-        });
-    }
-    // ---- list --------------------------------------------------------------
-    async list(opts) {
-        if (opts?.delimiter) this.#assertDelimiter();
-        const scopedPrefix = this.#listPrefix(opts?.prefix);
-        const res = await this.#exec('list', undefined, true, opts, (signal)=>this.#driver.list({
-                ...opts,
-                prefix: scopedPrefix,
-                signal
-            }));
-        return {
-            items: res.items.map((f)=>this.#relabel(f, this.#strip(f.key))),
-            prefixes: res.prefixes?.map((p)=>this.#strip(p)),
-            cursor: res.cursor
-        };
-    }
-    async *listAll(opts) {
-        let cursor = opts?.cursor;
-        do {
-            const page = await this.list({
-                ...opts,
-                cursor
-            });
-            for (const item of page.items)yield item;
-            cursor = page.cursor;
-        }while (cursor)
-    }
-    // ---- URLs / presign ----------------------------------------------------
-    async url(key, opts) {
-        if (!this.#driver.signedUrl?.supported) {
-            throw new StorageError('Unsupported', `${this.#driver.name}: url() not supported`);
-        }
-        return this.#exec('url', key, true, opts, (signal)=>this.#driver.url(this.#path(key), {
-                ...opts,
-                signal
-            }));
-    }
-    async signedUploadUrl(key, opts) {
-        this.#assertWritable();
-        if (!this.#driver.signedUrl?.upload) {
-            throw new StorageError('Unsupported', `${this.#driver.name}: signed uploads not supported`);
-        }
-        return this.#exec('signedUploadUrl', key, true, opts, (signal)=>this.#driver.signedUploadUrl(this.#path(key), {
-                ...opts,
-                signal
-            }));
-    }
-    /** Prefix-bound view of the driver's presigned-multipart capability. */ get signedMultipart() {
-        const cap = this.#driver.signedMultipart;
-        if (!cap) return undefined;
-        const path = (k)=>this.#path(k);
-        return {
-            create: (key, o)=>cap.create(path(key), o),
-            signPart: (key, uploadId, partNumber, o)=>cap.signPart(path(key), uploadId, partNumber, o),
-            complete: (key, uploadId, parts)=>cap.complete(path(key), uploadId, parts),
-            abort: (key, uploadId)=>cap.abort(path(key), uploadId)
-        };
-    }
-    // ---- low-level multipart ----------------------------------------------
-    async createMultipartUpload(key, opts) {
-        this.#assertWritable();
-        if (typeof this.#driver.createMultipartUpload !== 'function') {
-            throw new StorageError('Unsupported', `${this.#driver.name}: multipart not supported`);
-        }
-        return this.#driver.createMultipartUpload(this.#path(key), opts);
-    }
-    resumeMultipartUpload(key, uploadId) {
-        this.#assertWritable();
-        if (typeof this.#driver.resumeMultipartUpload !== 'function') {
-            throw new StorageError('Unsupported', `${this.#driver.name}: multipart resume not supported`);
-        }
-        return this.#driver.resumeMultipartUpload(this.#path(key), uploadId);
-    }
-    // ---- ergonomics --------------------------------------------------------
-    /** A key-bound handle over the common single-object operations. */ file(key) {
-        return {
-            key,
-            upload: (body, o)=>this.upload(key, body, o),
-            download: (o)=>this.download(key, o),
-            head: (o)=>this.head(key, o),
-            exists: (o)=>this.exists(key, o),
-            delete: (o)=>this.delete(key, o),
-            url: (o)=>this.url(key, o),
-            signedUploadUrl: (o)=>this.signedUploadUrl(key, o)
-        };
-    }
-    /** A read-only clone of this handle (mutations throw `ReadOnly`). */ readonly() {
-        return new Storage({
-            ...this.#opts,
-            readonly: true
-        });
-    }
-    // ---- internals ---------------------------------------------------------
-    #path(key) {
-        return joinKey(this.#prefix, sanitizeKey(key));
-    }
-    #strip(storedKey) {
-        return stripPrefix(this.#prefix, storedKey);
-    }
-    #listPrefix(prefix) {
-        if (!this.#prefix) return prefix;
-        return prefix ? `${this.#prefix}/${prefix}` : `${this.#prefix}/`;
-    }
-    #relabel(file, logicalKey) {
-        if (file.key === logicalKey) return file;
-        const name = logicalKey.slice(logicalKey.lastIndexOf('/') + 1);
-        return {
-            key: logicalKey,
-            name,
-            size: file.size,
-            type: file.type,
-            lastModified: file.lastModified,
-            etag: file.etag,
-            metadata: file.metadata,
-            arrayBuffer: ()=>file.arrayBuffer(),
-            text: ()=>file.text(),
-            blob: ()=>file.blob(),
-            stream: ()=>file.stream()
-        };
-    }
-    #assertWritable() {
-        if (this.#readonly) throw new StorageError('ReadOnly', 'storage handle is read-only');
-    }
-    #assertUploadSupported(opts) {
-        const d = this.#driver;
-        if (opts?.metadata && Object.keys(opts.metadata).length > 0 && !d.supportsMetadata) {
-            throw new StorageError('Unsupported', `${d.name}: metadata not supported`);
-        }
-        if (opts?.cacheControl && !d.supportsCacheControl) {
-            throw new StorageError('Unsupported', `${d.name}: cacheControl not supported`);
-        }
-    }
-    #assertRange() {
-        if (!this.#driver.supportsRange) {
-            throw new StorageError('Unsupported', `${this.#driver.name}: range reads not supported`);
-        }
-    }
-    #assertDelimiter() {
-        if (!this.#driver.supportsDelimiter) {
-            throw new StorageError('Unsupported', `${this.#driver.name}: delimiter not supported`);
-        }
-    }
-    async #exec(type, key, replayable, opts, fn) {
-        const started = Date.now();
-        const retries = replayable ? opts?.retries ?? this.#opts.retries : 0;
-        const maxRetries = normalizeRetry(retries).max;
-        const hooks = this.#opts.hooks;
-        try {
-            const result = await runWithRetry(fn, {
-                retries,
-                timeout: opts?.timeout ?? this.#opts.timeout,
-                signal: opts?.signal ?? this.#opts.signal
-            }, (info)=>hooks?.onRetry?.({
-                    type,
-                    key,
-                    attempt: info.attempt,
-                    maxRetries,
-                    delayMs: info.delayMs,
-                    error: info.error
-                }));
-            hooks?.onOperation?.({
-                type,
-                key,
-                status: 'success',
-                durationMs: Date.now() - started
-            });
-            return result;
-        } catch (e) {
-            const error = StorageError.wrap(e);
-            hooks?.onError?.({
-                type,
-                key,
-                error
-            });
-            hooks?.onOperation?.({
-                type,
-                key,
-                status: 'error',
-                durationMs: Date.now() - started,
-                error
-            });
-            throw error;
-        }
-    }
-}
-export function createStorage(opts) {
-    return new Storage(opts);
-}

package/dist/storage.module.d.ts

@@ -1,46 +0,0 @@
-import { type DynamicModule, type InferTokens, type Token } from '@velajs/vela';
-import type { StorageDriver, StorageHooks } from './storage.types';
-import type { StorageAuthorizer } from './http/authorizer.types';
-/** Options for mounting the HTTP upload/download controller for a bucket. */
-export interface StorageHttpOptions {
-    /** Mount path (relative to vela's globalPrefix). Default `/api/storage`. */
-    basePath?: string;
-    /** Fine-grained per-action authorizer (deny / allow / allow-with-overrides). */
-    authorize?: StorageAuthorizer;
-    /** Behavior when no `authorize` is set. Default `'deny'`. */
-    defaultPolicy?: 'deny' | 'allow';
-    /** `redirect` to a signed URL (default) or `proxy` bytes through the Worker. */
-    download?: 'redirect' | 'proxy';
-    /** Set `false` to configure options without mounting the controller. Default mounts. */
-    mountController?: boolean;
-    defaultExpiresIn?: number;
-    maxExpiresIn?: number;
-    maxUploadSize?: number;
-    maxListLimit?: number;
-    deleteConcurrency?: number;
-}
-export interface StorageModuleOptions {
-    driver: StorageDriver;
-    name?: string;
-    prefix?: string;
-    readonly?: boolean;
-    hooks?: StorageHooks;
-    http?: StorageHttpOptions;
-}
-export interface StorageModuleAsyncOptions<Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
-    inject?: Inject;
-    imports?: DynamicModule['imports'];
-    useFactory: (...deps: InferTokens<Inject>) => StorageDriver;
-    name?: string;
-    prefix?: string;
-    readonly?: boolean;
-    hooks?: StorageHooks;
-    http?: StorageHttpOptions;
-    key?: string;
-}
-export declare class StorageModule {
-    /** Synchronous registration — the driver is provided directly. */
-    static forRoot(options: StorageModuleOptions): DynamicModule;
-    /** Deferred / DI-driven registration — `useFactory` runs lazily on first use. */
-    static forRootAsync<const Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]>(options: StorageModuleAsyncOptions<Inject>): DynamicModule;
-}

package/dist/storage.module.js

@@ -1,113 +0,0 @@
-import { defineModule, lazyProvider, stableHash } from "@velajs/vela";
-import { createStorageController } from "./storage.controller.js";
-import { StorageService } from "./storage.service.js";
-import { DEFAULT_STORAGE_NAME, storageDriverBuilder, storageToken } from "./storage.tokens.js";
-/**
- * The stable, identifying subset of the HTTP options folded into the instance
- * key — matches what `buildControllers` bakes into the mounted controller so
- * two registrations that differ only in HTTP behavior get distinct keys.
- */ function httpKeyPart(http) {
-    if (!http || http.mountController === false) return {};
-    return {
-        basePath: http.basePath ?? '/api/storage',
-        download: http.download ?? 'redirect',
-        defaultPolicy: http.defaultPolicy ?? 'deny'
-    };
-}
-function buildControllers(name, serviceToken, http) {
-    if (!http || http.mountController === false) return [];
-    const resolved = {
-        driverName: name,
-        authorize: http.authorize,
-        defaultPolicy: http.defaultPolicy ?? 'deny',
-        download: http.download ?? 'redirect',
-        defaultExpiresIn: http.defaultExpiresIn ?? 900,
-        maxExpiresIn: http.maxExpiresIn ?? 3600,
-        maxUploadSize: http.maxUploadSize,
-        maxListLimit: http.maxListLimit ?? 1000,
-        deleteConcurrency: http.deleteConcurrency ?? 8
-    };
-    const basePath = http.basePath ?? '/api/storage';
-    return [
-        createStorageController(basePath, serviceToken, resolved)
-    ];
-}
-const { ConfigurableModuleClass } = defineModule({
-    name: 'Storage',
-    // Value-shaped identity only: never the (stateful) driver thunk. Same
-    // name+prefix+readonly+hooks+http dedups (HMR-idempotent); a distinct bucket
-    // name coexists.
-    key: (o)=>stableHash({
-            name: o.name ?? DEFAULT_STORAGE_NAME,
-            prefix: o.prefix ?? '',
-            readonly: !!o.readonly,
-            hooks: !!o.hooks,
-            ...httpKeyPart(o.http)
-        }),
-    setup: ({ OPTIONS, options })=>{
-        const name = options.name ?? DEFAULT_STORAGE_NAME;
-        const builderToken = storageDriverBuilder(name);
-        const serviceToken = name === DEFAULT_STORAGE_NAME ? StorageService : storageToken(name);
-        const svcOptions = {
-            name,
-            prefix: options.prefix,
-            readonly: options.readonly,
-            hooks: options.hooks
-        };
-        return {
-            providers: [
-                // Deferred, memoized driver construction — the seam that keeps
-                // Cloudflare bindings / `c.env` reads out of module load.
-                lazyProvider({
-                    provide: builderToken,
-                    inject: [
-                        OPTIONS
-                    ],
-                    useFactory: (o)=>o.driver()
-                }),
-                {
-                    provide: serviceToken,
-                    useFactory: (build)=>new StorageService(build, svcOptions),
-                    inject: [
-                        builderToken
-                    ]
-                }
-            ],
-            controllers: buildControllers(name, serviceToken, options.http),
-            exports: [
-                serviceToken,
-                builderToken
-            ]
-        };
-    }
-});
-export class StorageModule {
-    /** Synchronous registration — the driver is provided directly. */ static forRoot(options) {
-        const { driver, ...rest } = options;
-        return {
-            ...ConfigurableModuleClass.forRoot({
-                ...rest,
-                driver: ()=>driver
-            }),
-            module: StorageModule
-        };
-    }
-    /** Deferred / DI-driven registration — `useFactory` runs lazily on first use. */ static forRootAsync(options) {
-        const { useFactory, inject, imports, key, ...structural } = options;
-        return {
-            ...ConfigurableModuleClass.forRootAsync({
-                imports,
-                inject,
-                key,
-                ...structural,
-                // Wrap the caller's driver factory in a thunk so resolving the options
-                // token (at bootstrap) does NOT build the driver — only the first
-                // storage operation does.
-                useFactory: (...deps)=>({
-                        driver: ()=>useFactory(...deps)
-                    })
-            }),
-            module: StorageModule
-        };
-    }
-}

package/dist/storage.service.d.ts

@@ -1,42 +0,0 @@
-import { Storage } from './storage.facade';
-import type { Body, DeleteManyOptions, DeleteManyResult, DownloadOptions, ListOptions, ListResult, OperationOptions, SignedUpload, SignUploadOptions, StorageDriver, StorageHooks, StoredFile, UploadOptions, UploadResult, UrlOptions } from './storage.types';
-/**
- * Build the real driver on first property access and delegate to it. This is
- * the edge-binding-safe seam: the driver factory (which may read Cloudflare
- * bindings / `c.env` secrets) does not run at module load — only on the first
- * storage operation, which happens at request time.
- *
- * Functions are bound to the built driver so class-based drivers keep `this`.
- */
-export declare function lazyDriver(build: () => StorageDriver): StorageDriver;
-export interface StorageServiceOptions {
-    name: string;
-    prefix?: string;
-    readonly?: boolean;
-    hooks?: StorageHooks;
-}
-/**
- * The injectable consumers reach for. Wraps one bucket's {@link Storage}
- * facade (lazy driver construction), plus thin forwarders for the common
- * single-object operations so `service.upload(...)` works without reaching
- * through `.storage`.
- *
- * For multiple buckets, register `StorageModule.forRoot({ name })` per bucket
- * and inject with `@InjectStorage(name)`.
- */
-export declare class StorageService {
-    readonly storage: Storage;
-    readonly name: string;
-    constructor(build: () => StorageDriver, options: StorageServiceOptions);
-    upload(key: string, body: Body, opts?: UploadOptions): Promise<UploadResult>;
-    download(key: string, opts?: DownloadOptions): Promise<StoredFile>;
-    head(key: string, opts?: OperationOptions): Promise<StoredFile>;
-    exists(key: string, opts?: OperationOptions): Promise<boolean>;
-    delete(key: string, opts?: OperationOptions): Promise<void>;
-    deleteMany(keys: string[], opts?: DeleteManyOptions): Promise<DeleteManyResult>;
-    copy(from: string, to: string, opts?: OperationOptions): Promise<void>;
-    move(from: string, to: string, opts?: OperationOptions): Promise<void>;
-    list(opts?: ListOptions): Promise<ListResult>;
-    url(key: string, opts?: UrlOptions): Promise<string>;
-    signedUploadUrl(key: string, opts: SignUploadOptions): Promise<SignedUpload>;
-}