@cedarjs/uploads 7.0.1-next.333 → 7.0.1-next.467

package/dist/variants.d.ts

@@ -0,0 +1,207 @@
+import type { ContentDisposition, StorageProvider, StorageTargets, UploadVariantDatabase, UploadVariantRecord } from './types.js';
+/** The file a variant generator returns. */
+export interface UploadVariantFile {
+    /** The derived file's bytes. */
+    data: Uint8Array;
+    /** MIME type of `data`, for example `image/webp`. */
+    mimeType: string;
+    /**
+     * Filename for the derived file's `Upload` row. Defaults to the source's
+     * filename without its extension, plus the variant name and the extension
+     * of `mimeType`: `photo.jpg` becomes `photo-thumb-164.webp`.
+     */
+    filename?: string;
+}
+/** What a variant generator is called with. */
+export interface UploadVariantContext {
+    /** The source file's `Upload` row, without its inline `data`. */
+    source: UploadVariantRecord;
+    /** Name of the variant being made, for example `'thumb-164'`. */
+    variant: string;
+    /** Reads the source file's bytes from whichever target holds them. */
+    readSource(): Promise<Buffer>;
+    /**
+     * 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')`).
+     */
+    readVariant(name: string): Promise<Buffer | null>;
+}
+/**
+ * Makes one derived file (variant) from its source: a thumbnail from a
+ * photo, a preview image from a PDF, a poster frame from a video. This is
+ * the only part the app writes; the uploads package stores the result,
+ * links it to its source, and keeps track of it.
+ *
+ * Return `null` when this source cannot have this variant (a file type the
+ * generator does not handle). Both `null` and a thrown error are remembered
+ * as a failure and not retried until `retryFailedAfter` has passed.
+ */
+export type UploadVariantGenerator = (context: UploadVariantContext) => Promise<UploadVariantFile | null> | UploadVariantFile | null;
+/** A variant generator plus where its files are stored. */
+export interface UploadVariantDefinition {
+    generate: UploadVariantGenerator;
+    /** Storage target for this variant's files. Defaults to the `target` option. */
+    target?: StorageProvider;
+}
+export interface DefineUploadVariantsOptions<Name extends string> {
+    db: UploadVariantDatabase;
+    /**
+     * Every configured storage target. Used to read sources and to read and
+     * delete variants wherever they are stored.
+     */
+    targets: StorageTargets;
+    /** Storage target new variant files are written to, unless a variant names its own. */
+    target: StorageProvider;
+    /**
+     * The variants, by name, each with the function that makes it:
+     * `{ 'thumb-164': makeThumb, preview: makePdfPreview }`. Names may use
+     * letters, digits, `.`, `_` and `-`.
+     */
+    variants: Record<Name, UploadVariantGenerator | UploadVariantDefinition>;
+    /**
+     * How long a variant that could not be made is left alone before the
+     * next request tries again, in milliseconds. Defaults to one day.
+     */
+    retryFailedAfter?: number;
+    /**
+     * How long a claim to make a variant is honored, in milliseconds. A
+     * request that finds a claim older than this assumes its maker died and
+     * makes the variant itself. Defaults to ten minutes; set it above the
+     * slowest generator's running time.
+     */
+    claimTimeout?: number;
+    /**
+     * How often a request waiting for another process to finish making the
+     * same variant checks again, in milliseconds. Defaults to 250.
+     */
+    pollInterval?: number;
+    /**
+     * Called when a generator throws or its result cannot be stored. Defaults
+     * to `console.error`. The failure is remembered either way.
+     */
+    onError?: (error: unknown, info: {
+        sourceId: string;
+        variant: string;
+    }) => void;
+}
+/** What `regenerateVariants()` did. */
+export interface RegenerateVariantsResult {
+    /** Variant files deleted, made or failed alike. */
+    deleted: number;
+    /** Variants made again. */
+    made: number;
+    /** Variants that could not be made again (remembered as failed). */
+    failed: number;
+    /** Variants that could not be deleted; reported through `onError`. */
+    errors: number;
+}
+/** A source upload, by id or by its row. */
+export type UploadVariantSource = string | {
+    id: string;
+};
+/**
+ * Derived files (variants) of uploads: thumbnails, previews, poster frames.
+ * Returned by `defineUploadVariants()`.
+ */
+export interface UploadVariants<Name extends string> {
+    /** The configured variant names. */
+    names: readonly Name[];
+    /**
+     * The variant's `Upload` row, made now if it does not exist yet. Returns
+     * `null` when it could not be made and `retryFailedAfter` has not passed.
+     *
+     * Making a variant happens once: concurrent calls in this process share
+     * 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>;
+    /**
+     * 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
+     * list page.
+     */
+    findVariant(source: UploadVariantSource, name: Name): Promise<UploadVariantRecord | null>;
+    /**
+     * The made variants of many sources in one query, keyed by source id.
+     * Sources without that variant are left out. Never makes anything.
+     */
+    findVariants(sourceIds: string[], name: Name): Promise<Map<string, UploadVariantRecord>>;
+    /**
+     * 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<{
+        upload: UploadVariantRecord;
+        data: Buffer;
+    } | null>;
+    /**
+     * A URL a browser can load the variant from, made now if it does not
+     * 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?: {
+        expiresIn?: number;
+        disposition?: ContentDisposition;
+    }): Promise<string | null>;
+    /**
+     * 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.
+     */
+    regenerateVariants(name: Name, options?: {
+        remake?: boolean;
+        batchSize?: number;
+    }): Promise<RegenerateVariantsResult>;
+    /**
+     * Deletes all variants of a source, bytes first, then rows. `deleteFile()`
+     * does this for you when given `targets`.
+     */
+    deleteVariants(source: UploadVariantSource): Promise<number>;
+}
+/**
+ * Deletes every derived file (variant) of `source`: bytes first, then rows,
+ * like `deleteFile()`. Returns how many were deleted. `deleteFile()` calls
+ * this when given `targets`, so a source never goes without its variants.
+ */
+export declare function deleteVariants(source: UploadVariantSource, { db, targets }: {
+    db: UploadVariantDatabase;
+    targets: StorageTargets;
+}): Promise<number>;
+/**
+ * Declares the derived files (variants) uploads can have, such as
+ * thumbnails, previews or a video's poster frame, each with the function
+ * that makes it. **Experimental.**
+ *
+ * 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.
+ *
+ * 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
+ * or a third-party service as the app sees fit.
+ *
+ * @example
+ * export const uploadVariants = defineUploadVariants({
+ *   db,
+ *   targets,
+ *   target: targets.thumbnails,
+ *   variants: {
+ *     'thumb-164': async ({ readSource }) => ({
+ *       data: await sharp(await readSource()).resize(164, 164).webp().toBuffer(),
+ *       mimeType: 'image/webp',
+ *     }),
+ *   },
+ * })
+ *
+ * const thumb = await uploadVariants.getVariant(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

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