@adonis-agora/media 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/media
 
+## 0.5.0
+
+### Minor Changes
+
+- [#6](https://github.com/DavideCarvalho/adonis-media/pull/6) [`256a11e`](https://github.com/DavideCarvalho/adonis-media/commit/256a11e034118435b2c29a1b7ac7c0c6c05ac5b6) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add the `@adonis-agora/media/single-file` helper (`storeSingleFile` / `removeSingleFile` / `isSingleFileStoreAvailable`) for storing exactly one file per owner through a `single: true` collection, returning the stable public URL (plus an optional `thumb` conversion URL). Lets other packages delegate single-file uploads such as avatars to media without taking a hard dependency on it.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/src/single_file_store.d.ts

@@ -0,0 +1,58 @@
+import { MediaManager } from './media_manager.js';
+/**
+ * Store a single file for an owner and return stable public URLs. This is a thin, generic seam over
+ * {@link MediaManager} for callers (e.g. another Agora package storing an avatar) that only need to
+ * "replace this owner's one file and give me a URL", without touching the fuller library surface.
+ *
+ * Single-slot replacement is a property of the collection: the `collection` named here must be
+ * configured `single: true` in the app's `config/media.ts`. It is NOT an attach flag.
+ */
+export interface StoreSingleFileInput {
+    ownerType: string;
+    ownerId: string;
+    /** Must be configured `single: true` in the app's media config. */
+    collection: string;
+    fileName: string;
+    mimeType: string;
+    contents: Buffer;
+}
+export interface StoredSingleFile {
+    /** Public URL of the stored original. */
+    url: string;
+    /** Public URL of the `thumb` conversion, or `null` when that conversion isn't configured. */
+    thumbUrl: string | null;
+}
+export interface RemoveSingleFileInput {
+    ownerType: string;
+    ownerId: string;
+    collection: string;
+}
+/**
+ * Core of {@link storeSingleFile} driven by an explicit {@link MediaManager}, so tests can exercise
+ * it with an in-memory manager without booting an app. Attaches the file to the owner's collection
+ * (single-file replacement comes from the collection config) and resolves the original URL plus,
+ * best-effort, a `thumb` conversion URL.
+ */
+export declare function storeSingleFileWith(manager: MediaManager, input: StoreSingleFileInput): Promise<StoredSingleFile>;
+/**
+ * Core of {@link removeSingleFile} driven by an explicit {@link MediaManager}. Empties the owner's
+ * collection by deleting every record it holds (a single-file collection holds at most one).
+ */
+export declare function removeSingleFileWith(manager: MediaManager, input: RemoveSingleFileInput): Promise<void>;
+/**
+ * Store a single file for an owner via the app-bound {@link MediaManager}. Resolves the manager from
+ * the container, then delegates to {@link storeSingleFileWith}. The `collection` must be configured
+ * `single: true` in `config/media.ts` for prior files to be replaced.
+ */
+export declare function storeSingleFile(input: StoreSingleFileInput): Promise<StoredSingleFile>;
+/**
+ * Remove the owner's file in a collection via the app-bound {@link MediaManager}. Resolves the
+ * manager from the container, then delegates to {@link removeSingleFileWith}.
+ */
+export declare function removeSingleFile(input: RemoveSingleFileInput): Promise<void>;
+/**
+ * Whether the single-file store is usable — i.e. the {@link MediaManager} is bound in the app
+ * container. Callers use this to feature-detect media before routing a store through it.
+ */
+export declare function isSingleFileStoreAvailable(): Promise<boolean>;
+//# sourceMappingURL=single_file_store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"single_file_store.d.ts","sourceRoot":"","sources":["../../src/single_file_store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAG5F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlF;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,OAAO,CAAC,CAEnE"}

package/dist/src/single_file_store.js

@@ -0,0 +1,61 @@
+import app from '@adonisjs/core/services/app';
+import { MediaManager } from './media_manager.js';
+/**
+ * Core of {@link storeSingleFile} driven by an explicit {@link MediaManager}, so tests can exercise
+ * it with an in-memory manager without booting an app. Attaches the file to the owner's collection
+ * (single-file replacement comes from the collection config) and resolves the original URL plus,
+ * best-effort, a `thumb` conversion URL.
+ */
+export async function storeSingleFileWith(manager, input) {
+    const record = await manager.library.for(input.ownerType, input.ownerId).attach({
+        collection: input.collection,
+        fileName: input.fileName,
+        mimeType: input.mimeType,
+        contents: input.contents,
+    });
+    const url = await manager.library.url(record.id);
+    // The `thumb` conversion is optional: if the collection doesn't define it (or it can't be
+    // generated), there's simply no thumbnail — return null rather than failing the whole store.
+    let thumbUrl = null;
+    try {
+        thumbUrl = await manager.library.url(record.id, 'thumb');
+    }
+    catch {
+        thumbUrl = null;
+    }
+    return { url, thumbUrl };
+}
+/**
+ * Core of {@link removeSingleFile} driven by an explicit {@link MediaManager}. Empties the owner's
+ * collection by deleting every record it holds (a single-file collection holds at most one).
+ */
+export async function removeSingleFileWith(manager, input) {
+    const records = await manager.library.for(input.ownerType, input.ownerId).list(input.collection);
+    for (const record of records)
+        await manager.library.delete(record.id);
+}
+/**
+ * Store a single file for an owner via the app-bound {@link MediaManager}. Resolves the manager from
+ * the container, then delegates to {@link storeSingleFileWith}. The `collection` must be configured
+ * `single: true` in `config/media.ts` for prior files to be replaced.
+ */
+export async function storeSingleFile(input) {
+    const manager = await app.container.make(MediaManager);
+    return storeSingleFileWith(manager, input);
+}
+/**
+ * Remove the owner's file in a collection via the app-bound {@link MediaManager}. Resolves the
+ * manager from the container, then delegates to {@link removeSingleFileWith}.
+ */
+export async function removeSingleFile(input) {
+    const manager = await app.container.make(MediaManager);
+    return removeSingleFileWith(manager, input);
+}
+/**
+ * Whether the single-file store is usable — i.e. the {@link MediaManager} is bound in the app
+ * container. Callers use this to feature-detect media before routing a store through it.
+ */
+export async function isSingleFileStoreAvailable() {
+    return app.container.hasBinding(MediaManager);
+}
+//# sourceMappingURL=single_file_store.js.map

package/dist/src/single_file_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single_file_store.js","sourceRoot":"","sources":["../../src/single_file_store.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,6BAA6B,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiClD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAqB,EACrB,KAA2B;IAE3B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QAC9E,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAEjD,0FAA0F;IAC1F,6FAA6F;IAC7F,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAqB,EACrB,KAA4B;IAE5B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACjG,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAA2B;IAC/D,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACvD,OAAO,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAA4B;IACjE,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACvD,OAAO,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B;IAC9C,OAAO,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/media",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Media-library for AdonisJS — owner collections (MIME whitelist, single-file replace, ordering), image conversions (eager/lazy), and column attachments, all on top of @adonisjs/drive. Pluggable MediaStore (in-memory + Lucid) and ImageProcessor (sharp). Part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,11 @@
       "import": "./dist/src/services/main.js",
       "default": "./dist/src/services/main.js"
     },
+    "./single-file": {
+      "types": "./dist/src/single_file_store.d.ts",
+      "import": "./dist/src/single_file_store.js",
+      "default": "./dist/src/single_file_store.js"
+    },
     "./media_provider": {
       "types": "./dist/providers/media_provider.d.ts",
       "import": "./dist/providers/media_provider.js",