@adonis-agora/media 0.1.0 → 0.2.0

package/dist/src/types.d.ts

@@ -11,6 +11,12 @@ import type { Readable } from 'node:stream';
  */
 export interface Disk {
     put(key: string, contents: Uint8Array, options?: DiskWriteOptions): Promise<void>;
+    /**
+     * Write a stream straight to the disk without buffering it in memory (flydrive exposes this). Used
+     * for large uploads when no conversions are needed and the size is known up front. Optional so the
+     * structural contract stays minimal; callers fall back to {@link put} when it is absent.
+     */
+    putStream?(key: string, contents: Readable, options?: DiskWriteOptions): Promise<void>;
     getBytes(key: string): Promise<Uint8Array>;
     getStream(key: string): Promise<Readable>;
     exists(key: string): Promise<boolean>;
@@ -35,6 +41,118 @@ export interface DiskMetaData {
     etag?: string | undefined;
     lastModified?: Date | undefined;
 }
+/** One completed part of a native multipart upload: its number and the ETag S3 returned for it. */
+export interface MultipartPart {
+    partNumber: number;
+    etag: string;
+}
+/**
+ * Coarse feature descriptor for a disk, letting callers branch on what a backend supports without
+ * probing methods one by one. Advertised by disks that implement {@link ExtendedDisk}; the media
+ * library reads it structurally (via `isExtendedDisk`) and never depends on it statically.
+ */
+export interface DiskCapabilities {
+    /** Can issue signed, time-limited URLs ({@link Disk.getSignedUrl}). */
+    presign: boolean;
+    /** Supports native server-side multipart assembly ({@link MultipartUploadDisk}). */
+    multipart: boolean;
+    /** Can serve stable public URLs ({@link Disk.getUrl}). */
+    publicUrls: boolean;
+    /** Can enumerate keys under a prefix ({@link ExtendedDisk.list}). */
+    list: boolean;
+}
+/** Options for {@link ExtendedDisk.list}. */
+export interface ListOptions {
+    /** Delimiter that rolls deeper keys up into folder prefixes. Default `'/'`. */
+    delimiter?: string;
+    /** Opaque pagination cursor returned by a previous {@link ListResult}. */
+    cursor?: string;
+    /** Max entries per page. */
+    limit?: number;
+    /**
+     * Override the disk's configured bucket (admin cross-bucket browse). Ignored by disks without a
+     * bucket concept.
+     */
+    bucket?: string;
+}
+/** One file entry returned by {@link ExtendedDisk.list}. */
+export interface ListEntry {
+    /** Full key relative to the bucket/root. */
+    key: string;
+    /** Last path segment (file name, no trailing slash). */
+    name: string;
+    sizeBytes: number | null;
+    lastModified: Date | null;
+}
+/** One page of a {@link ExtendedDisk.list} enumeration. */
+export interface ListResult {
+    /** Sub-folder prefixes (each ends in the delimiter), from `CommonPrefixes`. */
+    folders: string[];
+    /** File entries directly under the prefix. */
+    files: ListEntry[];
+    /** Present when the page is truncated; pass back as {@link ListOptions.cursor}. */
+    cursor?: string;
+}
+/** Object metadata from {@link ExtendedDisk.stat} — size/content-type/last-modified without a body download. */
+export interface DiskStat {
+    size: number;
+    contentType?: string | undefined;
+    lastModified?: Date | undefined;
+}
+/** Optional destination overrides for {@link ExtendedDisk.copy}/{@link ExtendedDisk.move}. */
+export interface CopyOptions {
+    /** Copy into a different bucket than the disk's configured one (cross-bucket copy/move). */
+    toBucket?: string;
+}
+/**
+ * Optional add-on surface for disks that support richer object operations — cross-key/cross-bucket
+ * copy & move, batched deletes, prefix listing, and cheap metadata (`size`/`stat`) — plus a
+ * {@link DiskCapabilities} descriptor. Like {@link MultipartUploadDisk} it is kept OFF the base
+ * {@link Disk} contract on purpose (the in-memory/Drive disks don't provide it) and detected
+ * structurally at runtime via `isExtendedDisk`. The bundled `disks.s3()` disk implements it.
+ */
+export interface ExtendedDisk {
+    /** Coarse feature descriptor for this disk. */
+    readonly capabilities: DiskCapabilities;
+    /** Server-side copy an object to another key (and optionally another bucket). */
+    copy(from: string, to: string, options?: CopyOptions): Promise<void>;
+    /** Server-side move (copy then delete the source). Supports cross-bucket via {@link CopyOptions}. */
+    move(from: string, to: string, options?: CopyOptions): Promise<void>;
+    /** Delete many keys in as few round-trips as the backend allows. An empty array is a no-op. */
+    deleteMany(keys: string[]): Promise<void>;
+    /** Enumerate keys under a prefix, one page at a time. */
+    list(prefix: string, options?: ListOptions): Promise<ListResult>;
+    /** Object size in bytes, without downloading the body. */
+    size(key: string): Promise<number>;
+    /** Object metadata (size/content-type/last-modified), without downloading the body. */
+    stat(key: string): Promise<DiskStat>;
+}
+/**
+ * Optional add-on surface for disks that support native server-side multipart uploads (S3). It is
+ * kept OFF the base {@link Disk} contract on purpose — the in-memory/Drive disks don't provide it —
+ * and detected structurally at runtime via `isMultipartCapable`. Powers the two direct-S3 upload
+ * modes:
+ *
+ * - `proxy`: the client PUTs each part to the app, which forwards the bytes to S3 with
+ *   {@link MultipartUploadDisk.uploadPart} (bytes flow through the backend).
+ * - `direct`: the app issues presigned part URLs with
+ *   {@link MultipartUploadDisk.presignUploadPart}; the client uploads each part straight to S3 and
+ *   the app assembles them with {@link MultipartUploadDisk.completeMultipartUpload}.
+ */
+export interface MultipartUploadDisk {
+    /** Begin a multipart upload; returns the S3 `UploadId` that ties the parts together. */
+    createMultipartUpload(key: string, options?: DiskWriteOptions): Promise<{
+        uploadId: string;
+    }>;
+    /** Upload one part's bytes server-side (the `proxy` path). Returns that part's number + ETag. */
+    uploadPart(key: string, uploadId: string, partNumber: number, body: Uint8Array): Promise<MultipartPart>;
+    /** Issue a presigned URL the client PUTs one part to directly (the `direct` path). */
+    presignUploadPart(key: string, uploadId: string, partNumber: number, expiresInSeconds: number): Promise<string>;
+    /** Assemble the uploaded parts into the final object. */
+    completeMultipartUpload(key: string, uploadId: string, parts: MultipartPart[]): Promise<void>;
+    /** Discard an in-flight multipart upload and free its parts. */
+    abortMultipartUpload(key: string, uploadId: string): Promise<void>;
+}
 /**
  * Resolves a disk by name. In an AdonisJS app this is `(name) => drive.use(name)`; the
  * provider builds it from the booted Drive manager. Tests pass a resolver over fake disks.

package/dist/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,YAAY,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/upload_manager.d.ts

@@ -0,0 +1,127 @@
+import type { Readable } from 'node:stream';
+import type { StorageManager } from './storage_manager.js';
+import type { MultipartPart } from './types.js';
+import { type ResolvedUploadMode, type UploadMode } from './upload_mode.js';
+export interface UploadManagerOptions {
+    storage: StorageManager;
+    /** Global default upload mode (`auto` when omitted). */
+    mode?: UploadMode | undefined;
+    /** Default part size in bytes for direct multipart uploads. Default 8 MiB. */
+    partSize?: number | undefined;
+    /** Lifetime of presigned part URLs, in seconds. Default 3600. */
+    presignTtlSeconds?: number | undefined;
+    /** Emit `upload.*` diagnostics events (default true). */
+    emitDiagnostics?: boolean | undefined;
+}
+export interface InitiateDirectUploadInput {
+    /** Disk name; defaults to the manager's default disk. */
+    disk?: string;
+    /** Object key to write. Resolve this server-side (never trust the client) in your route. */
+    key: string;
+    /** Content-Type stamped on the final object. */
+    contentType?: string;
+    /** Public/private visibility for the final object. */
+    visibility?: 'public' | 'private';
+    /** Total size in bytes — used to pre-compute how many part URLs to hand back. */
+    size?: number;
+    /** Override the part size for this upload. */
+    partSize?: number;
+}
+export interface DirectUploadCreated {
+    uploadId: string;
+    key: string;
+    disk: string;
+    partSize: number;
+    parts: {
+        partNumber: number;
+        url: string;
+    }[];
+}
+export interface PresignPartInput {
+    disk?: string;
+    key: string;
+    uploadId: string;
+    partNumber: number;
+}
+export interface CompleteDirectUploadInput {
+    disk?: string;
+    key: string;
+    uploadId: string;
+    parts: MultipartPart[];
+}
+export interface AbortDirectUploadInput {
+    disk?: string;
+    key: string;
+    uploadId: string;
+}
+export interface ProxyUploadInput {
+    disk?: string;
+    key: string;
+    contents: Uint8Array | Readable;
+    contentType?: string;
+    visibility?: 'public' | 'private';
+}
+/**
+ * Coordinates the two direct-S3 upload strategies over a {@link StorageManager}:
+ *
+ * - **proxy** — the client sends bytes to the app, which streams them to the disk with
+ *   `put`/`putStream` (works on any disk). {@link proxyUpload} / {@link proxyUploadPart}.
+ * - **direct** — for multipart-capable disks (S3), the app hands the client presigned part URLs so
+ *   the client uploads straight to S3, then assembles the parts. {@link initiateDirect} /
+ *   {@link presignPart} / {@link completeDirect} / {@link abortDirect}.
+ *
+ * This is the framework-free core; the AdonisJS provider exposes it over HTTP routes and
+ * {@link MediaManager} delegates its `*DirectUpload` convenience methods here.
+ */
+export declare class UploadManager {
+    private readonly storage;
+    private readonly mode;
+    private readonly partSize;
+    private readonly presignTtlSeconds;
+    private readonly emitDiagnostics;
+    constructor(options: UploadManagerOptions);
+    /**
+     * Resolve the effective mode for a disk (`proxy`/`direct`), honouring the per-call override, the
+     * configured global default, and the disk's multipart capability. Throws when `direct` is forced
+     * on a disk that can't do multipart.
+     */
+    resolveMode(input?: {
+        disk?: string;
+        mode?: UploadMode;
+    }): ResolvedUploadMode;
+    /** Begin a direct multipart upload and return a presigned URL per part for the client to PUT to. */
+    initiateDirect(input: InitiateDirectUploadInput): Promise<DirectUploadCreated>;
+    /** Issue a presigned URL for a single (e.g. retried) part of an in-flight direct upload. */
+    presignPart(input: PresignPartInput): Promise<{
+        url: string;
+    }>;
+    /** Assemble the uploaded parts into the final object, closing out the direct upload. */
+    completeDirect(input: CompleteDirectUploadInput): Promise<{
+        key: string;
+        disk: string;
+    }>;
+    /** Discard an in-flight direct upload and free its parts on S3. */
+    abortDirect(input: AbortDirectUploadInput): Promise<void>;
+    /**
+     * Proxy upload: stream the whole body through the app to the disk in a single write. Uses the
+     * disk's `putStream` for a `Readable` (no in-memory buffering) and falls back to `put` for bytes.
+     * Works on any disk — no multipart capability required.
+     */
+    proxyUpload(input: ProxyUploadInput): Promise<{
+        key: string;
+        disk: string;
+    }>;
+    /**
+     * Proxy a single multipart part's bytes server-side (client PUTs the part to the app, the app
+     * forwards it to S3). Pairs with {@link initiateDirect}/{@link completeDirect} for a
+     * proxy-through-backend multipart flow on a multipart-capable disk.
+     */
+    proxyUploadPart(input: {
+        disk?: string;
+        key: string;
+        uploadId: string;
+        partNumber: number;
+        body: Uint8Array;
+    }): Promise<MultipartPart>;
+}
+//# sourceMappingURL=upload_manager.d.ts.map

package/dist/src/upload_manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_manager.d.ts","sourceRoot":"","sources":["../../src/upload_manager.ts"],"names":[],"mappings":"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"}

package/dist/src/upload_manager.js

@@ -0,0 +1,152 @@
+import { publishMedia } from './diagnostics.js';
+import { UploadNotSupportedError } from './errors.js';
+import { isMultipartCapable } from './multipart.js';
+import { resolveUploadMode } from './upload_mode.js';
+/** Default size of each multipart part when the caller gives none (8 MiB — S3's part minimum is 5 MiB). */
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+/** Default lifetime of a presigned part URL (1 hour). */
+const DEFAULT_PRESIGN_TTL_SECONDS = 3600;
+/**
+ * Coordinates the two direct-S3 upload strategies over a {@link StorageManager}:
+ *
+ * - **proxy** — the client sends bytes to the app, which streams them to the disk with
+ *   `put`/`putStream` (works on any disk). {@link proxyUpload} / {@link proxyUploadPart}.
+ * - **direct** — for multipart-capable disks (S3), the app hands the client presigned part URLs so
+ *   the client uploads straight to S3, then assembles the parts. {@link initiateDirect} /
+ *   {@link presignPart} / {@link completeDirect} / {@link abortDirect}.
+ *
+ * This is the framework-free core; the AdonisJS provider exposes it over HTTP routes and
+ * {@link MediaManager} delegates its `*DirectUpload` convenience methods here.
+ */
+export class UploadManager {
+    storage;
+    mode;
+    partSize;
+    presignTtlSeconds;
+    emitDiagnostics;
+    constructor(options) {
+        this.storage = options.storage;
+        this.mode = options.mode ?? 'auto';
+        this.partSize = options.partSize ?? DEFAULT_PART_SIZE;
+        this.presignTtlSeconds = options.presignTtlSeconds ?? DEFAULT_PRESIGN_TTL_SECONDS;
+        this.emitDiagnostics = options.emitDiagnostics ?? true;
+    }
+    /**
+     * Resolve the effective mode for a disk (`proxy`/`direct`), honouring the per-call override, the
+     * configured global default, and the disk's multipart capability. Throws when `direct` is forced
+     * on a disk that can't do multipart.
+     */
+    resolveMode(input) {
+        const diskName = input?.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        return resolveUploadMode({ global: this.mode, perCall: input?.mode }, isMultipartCapable(disk), diskName);
+    }
+    // --- direct mode ---------------------------------------------------------------------------
+    /** Begin a direct multipart upload and return a presigned URL per part for the client to PUT to. */
+    async initiateDirect(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(diskName);
+        const putOptions = input.contentType !== undefined || input.visibility !== undefined
+            ? {
+                ...(input.contentType !== undefined ? { contentType: input.contentType } : {}),
+                ...(input.visibility !== undefined ? { visibility: input.visibility } : {}),
+            }
+            : undefined;
+        const { uploadId } = await disk.createMultipartUpload(input.key, putOptions);
+        const partSize = input.partSize ?? this.partSize;
+        const partCount = input.size !== undefined ? Math.max(1, Math.ceil(input.size / partSize)) : 1;
+        const parts = [];
+        for (let n = 1; n <= partCount; n++) {
+            const url = await disk.presignUploadPart(input.key, uploadId, n, this.presignTtlSeconds);
+            parts.push({ partNumber: n, url });
+        }
+        if (this.emitDiagnostics) {
+            publishMedia('upload.start', {
+                id: uploadId,
+                disk: diskName,
+                key: input.key,
+                mode: 'direct',
+                size: input.size,
+                contentType: input.contentType,
+            });
+        }
+        return { uploadId, key: input.key, disk: diskName, partSize, parts };
+    }
+    /** Issue a presigned URL for a single (e.g. retried) part of an in-flight direct upload. */
+    async presignPart(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(diskName);
+        const url = await disk.presignUploadPart(input.key, input.uploadId, input.partNumber, this.presignTtlSeconds);
+        return { url };
+    }
+    /** Assemble the uploaded parts into the final object, closing out the direct upload. */
+    async completeDirect(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(diskName);
+        await disk.completeMultipartUpload(input.key, input.uploadId, input.parts);
+        if (this.emitDiagnostics) {
+            publishMedia('upload.complete', { id: input.uploadId, disk: diskName, key: input.key });
+        }
+        return { key: input.key, disk: diskName };
+    }
+    /** Discard an in-flight direct upload and free its parts on S3. */
+    async abortDirect(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(diskName);
+        await disk.abortMultipartUpload(input.key, input.uploadId);
+        if (this.emitDiagnostics) {
+            publishMedia('upload.abort', { id: input.uploadId, disk: diskName, key: input.key });
+        }
+    }
+    // --- proxy mode ----------------------------------------------------------------------------
+    /**
+     * Proxy upload: stream the whole body through the app to the disk in a single write. Uses the
+     * disk's `putStream` for a `Readable` (no in-memory buffering) and falls back to `put` for bytes.
+     * Works on any disk — no multipart capability required.
+     */
+    async proxyUpload(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        const writeOptions = input.contentType !== undefined || input.visibility !== undefined
+            ? {
+                ...(input.contentType !== undefined ? { contentType: input.contentType } : {}),
+                ...(input.visibility !== undefined ? { visibility: input.visibility } : {}),
+            }
+            : undefined;
+        if (input.contents instanceof Uint8Array) {
+            await disk.put(input.key, input.contents, writeOptions);
+        }
+        else if (disk.putStream) {
+            await disk.putStream(input.key, input.contents, writeOptions);
+        }
+        else {
+            // A disk without streaming support: buffer the stream, then `put`.
+            const chunks = [];
+            for await (const chunk of input.contents)
+                chunks.push(Buffer.from(chunk));
+            await disk.put(input.key, new Uint8Array(Buffer.concat(chunks)), writeOptions);
+        }
+        return { key: input.key, disk: diskName };
+    }
+    /**
+     * Proxy a single multipart part's bytes server-side (client PUTs the part to the app, the app
+     * forwards it to S3). Pairs with {@link initiateDirect}/{@link completeDirect} for a
+     * proxy-through-backend multipart flow on a multipart-capable disk.
+     */
+    async proxyUploadPart(input) {
+        const diskName = input.disk ?? this.storage.defaultDisk;
+        const disk = this.storage.disk(diskName);
+        if (!isMultipartCapable(disk))
+            throw new UploadNotSupportedError(diskName, 'proxy multipart part');
+        return disk.uploadPart(input.key, input.uploadId, input.partNumber, input.body);
+    }
+}
+//# sourceMappingURL=upload_manager.js.map

package/dist/src/upload_manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_manager.js","sourceRoot":"","sources":["../../src/upload_manager.ts"],"names":[],"mappings":"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"}

package/dist/src/upload_mode.d.ts

@@ -0,0 +1,27 @@
+/** Requested upload strategy. `auto` picks `direct` when the disk is multipart-capable, else `proxy`. */
+export type UploadMode = 'auto' | 'proxy' | 'direct';
+/** The concrete strategy after resolution — `auto` has been collapsed to one of these. */
+export type ResolvedUploadMode = 'proxy' | 'direct';
+/**
+ * The upload mode configured at each level. The most specific wins:
+ * per-call → per-disk → global → `auto`.
+ */
+export interface UploadModeLevels {
+    /** Global default from `config/media.ts` (`uploads.mode`). */
+    global?: UploadMode | undefined;
+    /** A per-disk override (unused by the bundled disks; reserved for future per-disk config). */
+    perDisk?: UploadMode | undefined;
+    /** A per-call override passed to the upload method. */
+    perCall?: UploadMode | undefined;
+}
+/**
+ * Decide whether an upload flows through the backend (`proxy` — the app streams bytes to the disk)
+ * or straight to the disk (`direct` — the app issues presigned multipart part URLs and the client
+ * uploads to S3 itself).
+ *
+ * - `proxy`: always allowed (every disk can accept bytes through `put`/`putStream`).
+ * - `direct`: requires a multipart-capable disk; otherwise throws {@link UploadNotSupportedError}.
+ * - `auto`: `direct` when the disk is multipart-capable, else `proxy`.
+ */
+export declare function resolveUploadMode(levels: UploadModeLevels, directCapable: boolean, diskName?: string): ResolvedUploadMode;
+//# sourceMappingURL=upload_mode.d.ts.map

package/dist/src/upload_mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_mode.d.ts","sourceRoot":"","sources":["../../src/upload_mode.ts"],"names":[],"mappings":"AAEA,yGAAyG;AACzG,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErD,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACjC,uDAAuD;IACvD,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,aAAa,EAAE,OAAO,EACtB,QAAQ,SAAS,GAChB,kBAAkB,CASpB"}

package/dist/src/upload_mode.js

@@ -0,0 +1,22 @@
+import { UploadNotSupportedError } from './errors.js';
+/**
+ * Decide whether an upload flows through the backend (`proxy` — the app streams bytes to the disk)
+ * or straight to the disk (`direct` — the app issues presigned multipart part URLs and the client
+ * uploads to S3 itself).
+ *
+ * - `proxy`: always allowed (every disk can accept bytes through `put`/`putStream`).
+ * - `direct`: requires a multipart-capable disk; otherwise throws {@link UploadNotSupportedError}.
+ * - `auto`: `direct` when the disk is multipart-capable, else `proxy`.
+ */
+export function resolveUploadMode(levels, directCapable, diskName = 'disk') {
+    const mode = levels.perCall ?? levels.perDisk ?? levels.global ?? 'auto';
+    if (mode === 'proxy')
+        return 'proxy';
+    if (mode === 'direct') {
+        if (!directCapable)
+            throw new UploadNotSupportedError(diskName);
+        return 'direct';
+    }
+    return directCapable ? 'direct' : 'proxy';
+}
+//# sourceMappingURL=upload_mode.js.map

package/dist/src/upload_mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_mode.js","sourceRoot":"","sources":["../../src/upload_mode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAqBtD;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAwB,EACxB,aAAsB,EACtB,QAAQ,GAAG,MAAM;IAEjB,MAAM,IAAI,GAAe,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC;IAErF,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACrC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,IAAI,CAAC,aAAa;YAAE,MAAM,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QAChE,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AAC5C,CAAC"}

package/dist/src/upload_sessions/factory.d.ts

@@ -0,0 +1,62 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { UploadSessionStore } from '../resumable_upload.js';
+/**
+ * Runtime context an {@link UploadSessionStoreFactory} thunk receives when the media provider builds
+ * the configured session store at boot. Carries the booted application so a driver can resolve a
+ * peer's service (the Lucid `db`).
+ */
+export interface UploadSessionStoreContext {
+    app: ApplicationService;
+}
+/**
+ * A configured resumable session store: a lazy thunk the media provider calls at boot to build the
+ * {@link UploadSessionStore}. Each factory imports its peer (`@adonisjs/lucid`) inside the thunk, so
+ * the driver only loads when actually selected — keeping that package optional.
+ */
+export type UploadSessionStoreFactory = (ctx: UploadSessionStoreContext) => Promise<UploadSessionStore>;
+/** Options for the Lucid-backed resumable session store. */
+export interface LucidUploadSessionStoreConfig {
+    /** Lucid connection name to use. Defaults to the `Database` default connection. */
+    connection?: string;
+    /** Sessions table name. Default `media_upload_sessions`. */
+    table?: string;
+    /** Parts side-index table name. Default `media_upload_parts`. */
+    partsTable?: string;
+}
+/**
+ * The resumable session-store factory namespace used in `config/media.ts` (mirrors {@link stores}):
+ *
+ * ```ts
+ * import { defineConfig, uploadSessions } from '@adonis-agora/media'
+ *
+ * export default defineConfig({
+ *   uploads: {
+ *     resumable: {
+ *       store: 'lucid',
+ *       stores: {
+ *         memory: uploadSessions.memory(),
+ *         lucid: uploadSessions.lucid({ connection: 'pg' }),
+ *       },
+ *       routes: { enabled: true },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare const uploadSessions: {
+    /** In-memory session store — single-process, non-durable. Handy for tests and scratch apps. */
+    memory(): UploadSessionStoreFactory;
+    /** Persist resumable sessions in SQL via `@adonisjs/lucid`. */
+    lucid(config?: LucidUploadSessionStoreConfig): UploadSessionStoreFactory;
+};
+/**
+ * Build the resumable session store selected by `config.store` from the `config.stores` map. A named
+ * store with no matching factory THROWS {@link UploadSessionStoreNotConfiguredError} (a non-durable
+ * fallback would silently lose resumable state); only the zero-config path (no `store` named)
+ * resolves to the in-memory store.
+ */
+export declare function resolveUploadSessionStore(config: {
+    store?: string;
+    stores?: Record<string, UploadSessionStoreFactory>;
+}, ctx: UploadSessionStoreContext): Promise<UploadSessionStore>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/src/upload_sessions/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/upload_sessions/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,kBAAkB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,GAAG,EAAE,yBAAyB,KAC3B,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,WAAW,6BAA6B;IAC5C,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,cAAc;IACzB,+FAA+F;cACrF,yBAAyB;IASnC,+DAA+D;mBACjD,6BAA6B,GAAQ,yBAAyB;CAW7E,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;CAAE,EAC9E,GAAG,EAAE,yBAAyB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAW7B"}

package/dist/src/upload_sessions/factory.js

@@ -0,0 +1,60 @@
+import { UploadSessionStoreNotConfiguredError } from '../errors.js';
+/**
+ * The resumable session-store factory namespace used in `config/media.ts` (mirrors {@link stores}):
+ *
+ * ```ts
+ * import { defineConfig, uploadSessions } from '@adonis-agora/media'
+ *
+ * export default defineConfig({
+ *   uploads: {
+ *     resumable: {
+ *       store: 'lucid',
+ *       stores: {
+ *         memory: uploadSessions.memory(),
+ *         lucid: uploadSessions.lucid({ connection: 'pg' }),
+ *       },
+ *       routes: { enabled: true },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export const uploadSessions = {
+    /** In-memory session store — single-process, non-durable. Handy for tests and scratch apps. */
+    memory() {
+        return async () => {
+            const { InMemoryUploadSessionStore } = await import('../testing/in_memory_upload_session_store.js');
+            return new InMemoryUploadSessionStore();
+        };
+    },
+    /** Persist resumable sessions in SQL via `@adonisjs/lucid`. */
+    lucid(config = {}) {
+        return async () => {
+            const db = (await import('@adonisjs/lucid/services/db')).default;
+            const { LucidUploadSessionStore } = await import('./lucid.js');
+            return new LucidUploadSessionStore(db, {
+                ...(config.connection !== undefined ? { connectionName: config.connection } : {}),
+                ...(config.table !== undefined ? { table: config.table } : {}),
+                ...(config.partsTable !== undefined ? { partsTable: config.partsTable } : {}),
+            });
+        };
+    },
+};
+/**
+ * Build the resumable session store selected by `config.store` from the `config.stores` map. A named
+ * store with no matching factory THROWS {@link UploadSessionStoreNotConfiguredError} (a non-durable
+ * fallback would silently lose resumable state); only the zero-config path (no `store` named)
+ * resolves to the in-memory store.
+ */
+export async function resolveUploadSessionStore(config, ctx) {
+    const name = config.store;
+    if (name) {
+        const factory = config.stores?.[name];
+        if (!factory)
+            throw new UploadSessionStoreNotConfiguredError(name);
+        return factory(ctx);
+    }
+    const { InMemoryUploadSessionStore } = await import('../testing/in_memory_upload_session_store.js');
+    return new InMemoryUploadSessionStore();
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/upload_sessions/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/upload_sessions/factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oCAAoC,EAAE,MAAM,cAAc,CAAC;AA+BpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,+FAA+F;IAC/F,MAAM;QACJ,OAAO,KAAK,IAAI,EAAE;YAChB,MAAM,EAAE,0BAA0B,EAAE,GAAG,MAAM,MAAM,CACjD,8CAA8C,CAC/C,CAAC;YACF,OAAO,IAAI,0BAA0B,EAAE,CAAC;QAC1C,CAAC,CAAC;IACJ,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,SAAwC,EAAE;QAC9C,OAAO,KAAK,IAAI,EAAE;YAChB,MAAM,EAAE,GAAG,CAAC,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC,CAAC,OAAO,CAAC;YACjE,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;YAC/D,OAAO,IAAI,uBAAuB,CAAC,EAAE,EAAE;gBACrC,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjF,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9E,CAAC,CAAC;QACL,CAAC,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAA8E,EAC9E,GAA8B;IAE9B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC;IAC1B,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,oCAAoC,CAAC,IAAI,CAAC,CAAC;QACnE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IACD,MAAM,EAAE,0BAA0B,EAAE,GAAG,MAAM,MAAM,CACjD,8CAA8C,CAC/C,CAAC;IACF,OAAO,IAAI,0BAA0B,EAAE,CAAC;AAC1C,CAAC"}