@cedarjs/uploads 8.0.0-canary.3427 → 8.0.0-canary.3429

package/README.md

@@ -17,9 +17,9 @@ File uploads and storage for CedarJS apps.
 - **Derived files (variants)**, experimental: thumbnails, previews, a video's
   poster frame. `defineUploadVariants()` takes one generator function per
   variant name and keeps the bookkeeping: variants are `Upload` rows linked
-  to their source, made once on first read even under concurrency, failures
-  remembered with a retry-after, `regenerateVariants()` to remake one name,
-  and deletion with the source.
+  to their source, made once when first acquired (`acquireVariant()`) even
+  under concurrency, failures remembered with a retry-after,
+  `regenerateVariants()` to remake one name, and deletion with the source.
 - **Content detection** (`detectContentType`, `acceptedContentType`) that
   checks what an uploaded file really is from its bytes, not from its name or
   the type the browser claimed: images, PDF, audio/video, and OpenDocument and

package/dist/variants.d.ts

@@ -24,9 +24,10 @@ export interface UploadVariantContext {
      * Reads another variant of the same source, making it first if it does
      * not exist yet. Returns `null` when that variant could not be made. This
      * is how one derived file is made from another, for example a PDF's
-     * thumbnail cut from its drawn first page (`readVariant('preview')`).
+     * thumbnail cut from its drawn first page
+     * (`acquireVariantData('preview')`).
      */
-    readVariant(name: string): Promise<Buffer | null>;
+    acquireVariantData(name: string): Promise<Buffer | null>;
 }
 /**
  * Makes one derived file (variant) from its source: a thumbnail from a
@@ -116,7 +117,7 @@ export interface UploadVariants<Name extends string> {
      * one attempt, and across processes a claim row decides who makes it
      * while the others wait for the result.
      */
-    getVariant(source: UploadVariantSource, name: Name): Promise<UploadVariantRecord | null>;
+    acquireVariant(source: UploadVariantSource, name: Name): Promise<UploadVariantRecord | null>;
     /**
      * The variant's `Upload` row if it has been made, or `null`. Never makes
      * anything; use it where making on demand would be too slow, such as a
@@ -132,7 +133,7 @@ export interface UploadVariants<Name extends string> {
      * The variant's row and bytes, made now if it does not exist yet, or
      * `null` when it could not be made.
      */
-    readVariant(source: UploadVariantSource, name: Name): Promise<{
+    acquireVariantData(source: UploadVariantSource, name: Name): Promise<{
         upload: UploadVariantRecord;
         data: Buffer;
     } | null>;
@@ -141,7 +142,7 @@ export interface UploadVariants<Name extends string> {
      * exist yet: a signed URL for object storage, a `data:` URI for database
      * targets. `null` when the variant could not be made.
      */
-    getVariantUrl(source: UploadVariantSource, name: Name, options?: {
+    acquireVariantUrl(source: UploadVariantSource, name: Name, options?: {
         expiresIn?: number;
         disposition?: ContentDisposition;
     }): Promise<string | null>;
@@ -149,7 +150,8 @@ export interface UploadVariants<Name extends string> {
      * Remakes every variant called `name`, for every source that has one
      * (made or failed), and leaves other variants alone. Use it after fixing
      * a generator. Each old file is deleted, then the variant is made again
-     * unless `remake` is `false`, in which case it is made on its next read.
+     * unless `remake` is `false`, in which case it is made the next time it
+     * is acquired.
      */
     regenerateVariants(name: Name, options?: {
         remake?: boolean;
@@ -177,12 +179,15 @@ export declare function deleteVariants(source: UploadVariantSource, { db, target
  *
  * The app supplies only the generators. The uploads package keeps the
  * bookkeeping: each variant is an `Upload` row linked to its source by
- * `sourceId` and named by `variant`; it is made on first read, once even
- * when several requests or processes ask at the same moment; a variant
- * that cannot be made is remembered and tried again after
- * `retryFailedAfter`; `regenerateVariants()` remakes every variant of one
- * name; and `deleteFile()` with `targets` deletes a source's variants with
- * it.
+ * `sourceId` and named by `variant`; it is made the first time it is
+ * acquired, once even when several requests or processes ask at the same
+ * moment; a variant that cannot be made is remembered and tried again
+ * after `retryFailedAfter`; `regenerateVariants()` remakes every variant of
+ * one name; and `deleteFile()` with `targets` deletes a source's variants
+ * with it.
+ *
+ * Methods that make a variant when it is missing are named `acquire*`;
+ * `find*` only looks and never makes anything.
  *
  * The package does not make images or read videos itself. A generator is
  * any function from source bytes to new bytes, using sharp, pdf.js, ffmpeg
@@ -201,7 +206,7 @@ export declare function deleteVariants(source: UploadVariantSource, { db, target
  *   },
  * })
  *
- * const thumb = await uploadVariants.getVariant(photo.uploadId, 'thumb-164')
+ * const thumb = await uploadVariants.acquireVariant(photo.uploadId, 'thumb-164')
  */
 export declare function defineUploadVariants<Name extends string>(options: DefineUploadVariantsOptions<Name>): UploadVariants<Name>;
 //# sourceMappingURL=variants.d.ts.map

package/dist/variants.d.ts.map

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

package/dist/variants.js

@@ -167,7 +167,7 @@ function defineUploadVariants(options) {
     if (source.sourceId) {
       throw new UploadError(
         "NOT_SUPPORTED",
-        `Upload '${sourceId}' is itself a variant. Variants are made from original uploads only; use \`readVariant()\` in a generator to make one variant from another.`
+        `Upload '${sourceId}' is itself a variant. Variants are made from original uploads only; use \`acquireVariantData()\` in a generator to make one variant from another.`
       );
     }
     return source;
@@ -193,7 +193,7 @@ function defineUploadVariants(options) {
         source,
         variant: name,
         readSource: () => readBytes(db, targets, source),
-        readVariant: async (other) => {
+        acquireVariantData: async (other) => {
           const made = await obtainFor(
             keyOf(source.id, name),
             source.id,
@@ -369,7 +369,7 @@ function defineUploadVariants(options) {
     attempt.then(forget, forget);
     return attempt;
   };
-  const getVariant = (source, name) => obtain(idOf(source), name, []);
+  const acquireVariant = (source, name) => obtain(idOf(source), name, []);
   const findVariant = async (source, name) => {
     definitionOf(name);
     return db.upload.findFirst({
@@ -395,15 +395,15 @@ function defineUploadVariants(options) {
     }
     return bySource;
   };
-  const readVariant = async (source, name) => {
-    const upload = await getVariant(source, name);
+  const acquireVariantData = async (source, name) => {
+    const upload = await acquireVariant(source, name);
     if (!upload) {
       return null;
     }
     return { upload, data: await readBytes(db, targets, upload) };
   };
-  const getVariantUrl = async (source, name, urlOptions = {}) => {
-    const upload = await getVariant(source, name);
+  const acquireVariantUrl = async (source, name, urlOptions = {}) => {
+    const upload = await acquireVariant(source, name);
     if (!upload) {
       return null;
     }
@@ -464,10 +464,12 @@ function defineUploadVariants(options) {
         }
         if (remake) {
           await inFlight.get(keyOf(sourceId, name))?.catch(() => null);
-          const made = await getVariant(sourceId, name).catch((e) => {
-            onError(e, { sourceId, variant: name });
-            return null;
-          });
+          const made = await acquireVariant(sourceId, name).catch(
+            (e) => {
+              onError(e, { sourceId, variant: name });
+              return null;
+            }
+          );
           if (made) {
             result.made += 1;
           } else {
@@ -483,11 +485,11 @@ function defineUploadVariants(options) {
   };
   return {
     names,
-    getVariant,
+    acquireVariant,
     findVariant,
     findVariants,
-    readVariant,
-    getVariantUrl,
+    acquireVariantData,
+    acquireVariantUrl,
     regenerateVariants,
     deleteVariants: (source) => deleteVariants(source, { db, targets })
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedarjs/uploads",
-  "version": "8.0.0-canary.3427",
+  "version": "8.0.0-canary.3429",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cedarjs/cedar.git",
@@ -43,9 +43,9 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@cedarjs/api": "8.0.0-canary.3427",
-    "@cedarjs/context": "8.0.0-canary.3427",
-    "@cedarjs/graphql-server": "8.0.0-canary.3427",
+    "@cedarjs/api": "8.0.0-canary.3429",
+    "@cedarjs/context": "8.0.0-canary.3429",
+    "@cedarjs/graphql-server": "8.0.0-canary.3429",
     "@fastify/multipart": "9.4.0",
     "graphql": "16.14.2",
     "mime-types": "2.1.35"
@@ -55,8 +55,8 @@
     "@arethetypeswrong/cli": "0.18.5",
     "@aws-sdk/client-s3": "3.1149.0",
     "@aws-sdk/s3-request-presigner": "3.1149.0",
-    "@cedarjs/framework-tools": "8.0.0-canary.3427",
-    "@cedarjs/web": "8.0.0-canary.3427",
+    "@cedarjs/framework-tools": "8.0.0-canary.3429",
+    "@cedarjs/web": "8.0.0-canary.3429",
     "@prisma/adapter-better-sqlite3": "7.10.0",
     "@prisma/client": "7.10.0",
     "@testing-library/dom": "10.4.2",
@@ -90,7 +90,7 @@
     "@apollo/client": "4.3.3",
     "@aws-sdk/client-s3": "^3.0.0",
     "@aws-sdk/s3-request-presigner": "^3.0.0",
-    "@cedarjs/web": "8.0.0-canary.3427",
+    "@cedarjs/web": "8.0.0-canary.3429",
     "@uppy/aws-s3": "^6.0.0",
     "@uppy/core": "^6.0.0",
     "@uppy/dashboard": "^6.0.0",