@velajs/storage 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -1,17 +1,271 @@
-export { Storage, createStorage } from './storage.facade';
-export type { FileHandle } from './storage.facade';
-export { StorageModule } from './storage.module';
-export type { StorageModuleOptions, StorageModuleAsyncOptions } from './storage.module';
-export { StorageService, lazyDriver } from './storage.service';
-export type { StorageServiceOptions } from './storage.service';
-export { InjectStorage } from './decorators/inject-storage.decorator';
-export { DEFAULT_STORAGE_NAME, storageDriverBuilder, storageToken } from './storage.tokens';
-export { createStorageController } from './storage.controller';
-export type { ResolvedHttpOptions } from './storage.controller';
-export type { StorageHttpOptions } from './storage.module';
-export type { StorageAction, StorageAuthContext, StorageAuthResult, StorageAuthorizer, } from './http/authorizer.types';
-export type { SignUploadRequest, SignUploadResponse, MultipartCreateRequest, MultipartCreateResponse, SignPartRequest, SignPartResponse, MultipartCompleteRequest, MultipartCompleteResponse, MultipartAbortRequest, DeleteRequest, ListResponse, StoredFileMeta, SignDownloadResponse, OkResponse, StorageWireErrorCode, StorageErrorBody, } from './http/protocol.types';
-export { StorageError, isAbort } from './storage.error';
-export type { StorageErrorCode, StorageErrorOptions } from './storage.error';
-export { isSafeKey, sanitizeKey, normalizePrefix, joinKey, stripPrefix } from './object-key';
-export type { Body, PartBody, OperationOptions, RetryOptions, RetryBackoffContext, UploadProgress, MultipartOptions, UploadOptions, UploadResult, ByteRange, DownloadOptions, StoredFile, ListOptions, ListResult, DeleteManyOptions, DeleteManyError, DeleteManyResult, UrlOptions, SignUploadOptions, SignedUpload, SignedUrlCapability, CreateMultipartOptions, UploadedPart, MultipartUpload, SignedMultipartCreate, SignedPart, SignedMultipartCapability, StorageDriver, StorageCapabilities, StorageHooks, StorageHookEvent, StorageOptions, } from './storage.types';
+import { A as UploadResult, C as StorageDriver, D as StoredFile, E as StorageOptions, F as StorageErrorOptions, I as isAbort, M as UrlOptions, N as StorageError, O as UploadOptions, P as StorageErrorCode, S as StorageCapabilities, T as StorageHooks, _ as SignedMultipartCapability, a as DeleteManyOptions, b as SignedUpload, c as ListOptions, d as MultipartUpload, f as OperationOptions, g as SignUploadOptions, h as RetryOptions, i as DeleteManyError, j as UploadedPart, k as UploadProgress, l as ListResult, m as RetryBackoffContext, n as ByteRange, o as DeleteManyResult, p as PartBody, r as CreateMultipartOptions, s as DownloadOptions, t as Body, u as MultipartOptions, v as SignedMultipartCreate, w as StorageHookEvent, x as SignedUrlCapability, y as SignedPart } from "./storage.types-BJN7Yp1J.js";
+import { a as MultipartCompleteResponse, c as OkResponse, d as SignPartResponse, f as SignUploadRequest, g as StoredFileMeta, h as StorageWireErrorCode, i as MultipartCompleteRequest, l as SignDownloadResponse, m as StorageErrorBody, n as ListResponse, o as MultipartCreateRequest, p as SignUploadResponse, r as MultipartAbortRequest, s as MultipartCreateResponse, t as DeleteRequest, u as SignPartRequest } from "./protocol.types-C5PPBD12.js";
+import { DynamicModule, InferTokens, InjectionToken, Token, Type } from "@velajs/vela";
+import { Context } from "hono";
+//#region src/storage.facade.d.ts
+/**
+ * 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.
+ */
+declare class Storage {
+  #private;
+  constructor(opts: StorageOptions);
+  get raw(): unknown;
+  get driver(): StorageDriver;
+  get capabilities(): StorageCapabilities;
+  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>;
+  delete(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>;
+  listAll(opts?: ListOptions): AsyncGenerator<StoredFile>;
+  url(key: string, opts?: UrlOptions): Promise<string>;
+  signedUploadUrl(key: string, opts: SignUploadOptions): Promise<SignedUpload>;
+  /** Prefix-bound view of the driver's presigned-multipart capability. */
+  get signedMultipart(): SignedMultipartCapability | undefined;
+  createMultipartUpload(key: string, opts?: CreateMultipartOptions): Promise<MultipartUpload>;
+  resumeMultipartUpload(key: string, uploadId: string): MultipartUpload;
+  /** A key-bound handle over the common single-object operations. */
+  file(key: string): FileHandle;
+  /** A read-only clone of this handle (mutations throw `ReadOnly`). */
+  readonly(): Storage;
+}
+interface FileHandle {
+  readonly key: string;
+  upload(body: Body, opts?: UploadOptions): Promise<UploadResult>;
+  download(opts?: DownloadOptions): Promise<StoredFile>;
+  head(opts?: OperationOptions): Promise<StoredFile>;
+  exists(opts?: OperationOptions): Promise<boolean>;
+  delete(opts?: OperationOptions): Promise<void>;
+  url(opts?: UrlOptions): Promise<string>;
+  signedUploadUrl(opts: SignUploadOptions): Promise<SignedUpload>;
+}
+declare function createStorage(opts: StorageOptions): Storage;
+//#endregion
+//#region src/http/authorizer.types.d.ts
+/**
+ * The typed action a request wants to perform. The authorizer receives this
+ * and can deny, allow, or allow-with-overrides (rewriting the effective key /
+ * prefix / limits) — the load-bearing IDOR / cross-tenant guard.
+ */
+type StorageAction = {
+  type: 'sign-upload';
+  key: string;
+  contentType?: string;
+  size?: number;
+} | {
+  type: 'multipart-create';
+  key: string;
+  contentType?: string;
+} | {
+  type: 'multipart-sign-part';
+  key: string;
+  uploadId: string;
+  partNumber: number;
+} | {
+  type: 'multipart-complete';
+  key: string;
+  uploadId: string;
+} | {
+  type: 'multipart-abort';
+  key: string;
+  uploadId: string;
+} | {
+  type: 'download';
+  key: string;
+} | {
+  type: 'head';
+  key: string;
+} | {
+  type: 'list';
+  prefix?: string;
+} | {
+  type: 'delete';
+  keys: string[];
+};
+interface StorageAuthContext {
+  /** The raw Web `Request` (edge-safe). */
+  req: Request;
+  /** The Hono context — `c.env` (bindings/secrets), `c.get('user')` from an upstream guard. */
+  ctx: Context;
+  /** The bucket name this controller is bound to. */
+  driver: string;
+}
+/** Return this to ALLOW with server-side modifications. */
+interface StorageAuthResult {
+  key?: string;
+  keys?: string[];
+  prefix?: string;
+  maxSize?: number;
+  expiresIn?: number;
+  metadata?: Record<string, string>;
+}
+type StorageAuthorizer = (action: StorageAction, context: StorageAuthContext) => boolean | StorageAuthResult | Promise<boolean | StorageAuthResult>;
+//#endregion
+//#region src/storage.module.d.ts
+/** Options for mounting the HTTP upload/download controller for a bucket. */
+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;
+}
+interface StorageModuleOptions {
+  driver: StorageDriver;
+  name?: string;
+  prefix?: string;
+  readonly?: boolean;
+  hooks?: StorageHooks;
+  http?: StorageHttpOptions;
+}
+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;
+}
+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;
+}
+//#endregion
+//#region src/storage.service.d.ts
+/**
+ * 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`.
+ */
+declare function lazyDriver(build: () => StorageDriver): StorageDriver;
+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)`.
+ */
+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>;
+}
+//#endregion
+//#region src/decorators/inject-storage.decorator.d.ts
+/**
+ * Inject the {@link StorageService} for a named bucket.
+ *
+ * ```ts
+ * class UploadService {
+ *   constructor(
+ *     @InjectStorage() private readonly uploads: StorageService,          // default bucket
+ *     @InjectStorage('backups') private readonly backups: StorageService, // named bucket
+ *   ) {}
+ * }
+ * ```
+ *
+ * The default bucket resolves the `StorageService` class token directly (so
+ * plain `@Inject(StorageService)` and `Test.overrideProvider(StorageService)`
+ * keep working); named buckets resolve their per-name token.
+ */
+declare function InjectStorage(name?: string): ParameterDecorator;
+//#endregion
+//#region src/storage.tokens.d.ts
+/** Bucket name used when a registration omits `name`. */
+declare const DEFAULT_STORAGE_NAME = "default";
+/** Internal token holding the lazy driver-construction thunk for `name`. */
+declare function storageDriverBuilder(name: string): InjectionToken<() => StorageDriver>;
+/**
+ * Token that resolves to the {@link StorageService} for a named bucket.
+ * The default bucket uses the `StorageService` class token directly (see
+ * `@InjectStorage()`); named buckets use this.
+ */
+declare function storageToken(name: string): InjectionToken<StorageService>;
+//#endregion
+//#region src/storage.controller.d.ts
+interface ResolvedHttpOptions {
+  driverName: string;
+  authorize?: StorageAuthorizer;
+  defaultPolicy: 'deny' | 'allow';
+  download: 'redirect' | 'proxy';
+  defaultExpiresIn: number;
+  maxExpiresIn: number;
+  maxUploadSize?: number;
+  maxListLimit: number;
+  deleteConcurrency: number;
+}
+/**
+ * Build a vela controller exposing presigned/multipart upload + download
+ * endpoints for one bucket. Factory-decorated (like better-auth's catch-all)
+ * so `basePath` bakes in at decoration time. Consumes the {@link StorageService}
+ * facade so gating/retry/prefix apply uniformly on the HTTP path.
+ */
+declare function createStorageController(basePath: string, serviceToken: Token<StorageService>, http: ResolvedHttpOptions): Type;
+//#endregion
+//#region src/object-key.d.ts
+/**
+ * True when `key` is a safe object key:
+ * - non-empty, not longer than 1024 bytes (S3's limit)
+ * - no leading `/`
+ * - no `.` / `..` path segments (traversal)
+ * - no control characters
+ * - no backslashes (Windows-style separators)
+ */
+declare function isSafeKey(key: string): boolean;
+/** Return `key` if safe, else throw `StorageError('InvalidKey')`. */
+declare function sanitizeKey(key: string): string;
+/** Normalize a prefix: drop leading/trailing slashes, collapse to '' when empty. */
+declare function normalizePrefix(prefix: string | undefined): string;
+/** Join a normalized prefix and a key with a single '/'. */
+declare function joinKey(prefix: string, key: string): string;
+/** Strip a normalized prefix from a stored key (for surfacing to callers). */
+declare function stripPrefix(prefix: string, key: string): string;
+//#endregion
+export { type Body, type ByteRange, type CreateMultipartOptions, DEFAULT_STORAGE_NAME, type DeleteManyError, type DeleteManyOptions, type DeleteManyResult, type DeleteRequest, type DownloadOptions, type FileHandle, InjectStorage, type ListOptions, type ListResponse, type ListResult, type MultipartAbortRequest, type MultipartCompleteRequest, type MultipartCompleteResponse, type MultipartCreateRequest, type MultipartCreateResponse, type MultipartOptions, type MultipartUpload, type OkResponse, type OperationOptions, type PartBody, type ResolvedHttpOptions, type RetryBackoffContext, type RetryOptions, type SignDownloadResponse, type SignPartRequest, type SignPartResponse, type SignUploadOptions, type SignUploadRequest, type SignUploadResponse, type SignedMultipartCapability, type SignedMultipartCreate, type SignedPart, type SignedUpload, type SignedUrlCapability, Storage, type StorageAction, type StorageAuthContext, type StorageAuthResult, type StorageAuthorizer, type StorageCapabilities, type StorageDriver, StorageError, type StorageErrorBody, type StorageErrorCode, type StorageErrorOptions, type StorageHookEvent, type StorageHooks, type StorageHttpOptions, StorageModule, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageOptions, StorageService, type StorageServiceOptions, type StorageWireErrorCode, type StoredFile, type StoredFileMeta, type UploadOptions, type UploadProgress, type UploadResult, type UploadedPart, type UrlOptions, createStorage, createStorageController, isAbort, isSafeKey, joinKey, lazyDriver, normalizePrefix, sanitizeKey, storageDriverBuilder, storageToken, stripPrefix };
+//# sourceMappingURL=index.d.ts.map