@michaelthielemann/kestrel-images-default 5.0.0

package/dist/module.d.ts

@@ -0,0 +1,299 @@
+import { z } from "zod";
+import { type Context } from "@michaelthielemann/kestrel/context";
+import { type Variant } from "./impl.ts";
+export declare const configSchema: z.ZodObject<{
+    sizes: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodOptional<z.ZodNumber>;
+        fit: z.ZodDefault<z.ZodEnum<["inside", "cover"]>>;
+        format: z.ZodDefault<z.ZodEnum<["webp", "original"]>>;
+        quality: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        width: number;
+        fit: "inside" | "cover";
+        format: "webp" | "original";
+        quality: number;
+        height?: number | undefined;
+    }, {
+        name: string;
+        width: number;
+        height?: number | undefined;
+        fit?: "inside" | "cover" | undefined;
+        format?: "webp" | "original" | undefined;
+        quality?: number | undefined;
+    }>, {
+        name: string;
+        width: number;
+        fit: "inside" | "cover";
+        format: "webp" | "original";
+        quality: number;
+        height?: number | undefined;
+    }, {
+        name: string;
+        width: number;
+        height?: number | undefined;
+        fit?: "inside" | "cover" | undefined;
+        format?: "webp" | "original" | undefined;
+        quality?: number | undefined;
+    }>, "many">>;
+    prefix: z.ZodDefault<z.ZodString>;
+    publicPath: z.ZodDefault<z.ZodString>;
+    media: z.ZodDefault<z.ZodObject<{
+        collection: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        collection: string;
+    }, {
+        collection: string;
+    }>>;
+    chunk: z.ZodDefault<z.ZodNumber>;
+    staleAfterMs: z.ZodDefault<z.ZodNumber>;
+    maxAttempts: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    prefix: string;
+    publicPath: string;
+    media: {
+        collection: string;
+    };
+    chunk: number;
+    staleAfterMs: number;
+    maxAttempts: number;
+    sizes?: {
+        name: string;
+        width: number;
+        fit: "inside" | "cover";
+        format: "webp" | "original";
+        quality: number;
+        height?: number | undefined;
+    }[] | undefined;
+}, {
+    sizes?: {
+        name: string;
+        width: number;
+        height?: number | undefined;
+        fit?: "inside" | "cover" | undefined;
+        format?: "webp" | "original" | undefined;
+        quality?: number | undefined;
+    }[] | undefined;
+    prefix?: string | undefined;
+    publicPath?: string | undefined;
+    media?: {
+        collection: string;
+    } | undefined;
+    chunk?: number | undefined;
+    staleAfterMs?: number | undefined;
+    maxAttempts?: number | undefined;
+}>;
+declare const _default: import("@michaelthielemann/kestrel/defineModule").ModuleDefinition<"images/default", {
+    register: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: import("./sizes.ts").SizeRow[];
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    listSizes: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Ok<{
+        result: import("./sizes.ts").SizeRow[];
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    generate: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: {
+            items: {
+                id: string;
+                variants: Variant[];
+            }[];
+        };
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: {
+            id: string;
+            variants: Variant[];
+        };
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    sync: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: import("./impl.ts").Job;
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    resume: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: import("./impl.ts").Job | null;
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    prune: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: {
+            sizes: number;
+            variants: number;
+        };
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    readStatus: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: import("./impl.ts").ImagesStatus;
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    remove: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<Context>>;
+    removeMany: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<Context>>;
+    attach: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: {
+            variants: {
+                size: string;
+                width: number;
+                height: number;
+                format: string;
+                bytes: number;
+                state: Variant["state"];
+                path: string;
+            }[];
+            id?: unknown;
+            items?: unknown;
+        };
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: {
+            items: {
+                variants: {
+                    size: string;
+                    width: number;
+                    height: number;
+                    format: string;
+                    bytes: number;
+                    state: Variant["state"];
+                    path: string;
+                }[];
+            }[];
+            id?: unknown;
+        };
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    serve: (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: import("@michaelthielemann/kestrel/context").BinaryResult;
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+    export: (dir: string) => (ctx: Context) => Promise<import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError<string>> | import("@michaelthielemann/kestrel/result").Ok<{
+        result: {
+            variants: {
+                written: number;
+                skipped: number;
+            };
+        };
+        runId: string;
+        requestId?: string;
+        trigger: import("@michaelthielemann/kestrel/context").Trigger;
+        payload: Record<string, unknown>;
+        params: Record<string, string>;
+        headers: Record<string, string>;
+        files: import("@michaelthielemann/kestrel/context").UploadedFile[];
+        ip?: string;
+        fail(code: import("@michaelthielemann/kestrel/errors").CoreCode, message: string, details?: Record<string, unknown>): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        fail(error: import("@michaelthielemann/kestrel/errors").KestrelError): import("@michaelthielemann/kestrel/result").Err<import("@michaelthielemann/kestrel/errors").KestrelError>;
+        done(result: unknown): import("@michaelthielemann/kestrel/result").Ok<Context>;
+    }>>;
+}>;
+export default _default;

package/dist/module.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import { BLOBSTORE } from "@michaelthielemann/kestrel-contracts/blobstore";
+import { PERSISTENCE } from "@michaelthielemann/kestrel-contracts/persistence";
+import { binaryResult, first, stepFactory } from "@michaelthielemann/kestrel/context";
+import { defineModule } from "@michaelthielemann/kestrel/defineModule";
+import { isErr, ok } from "@michaelthielemann/kestrel/result";
+import { DEFAULT_MAX_ATTEMPTS, createImages } from "./impl.js";
+import { sizeSchema } from "./sizes.js";
+export const configSchema = z
+    .object({
+    sizes: z.array(sizeSchema).optional(),
+    prefix: z.string().regex(/^([A-Za-z0-9._-]+\/)+$/, 'prefix must be one or more "<segment>/" parts, e.g. "media-variants/"').default("media-variants/"),
+    publicPath: z.string().regex(/^\/[A-Za-z0-9._/-]*$/).default("/media"),
+    media: z.object({ collection: z.string().min(1) }).default({ collection: "media_items" }),
+    chunk: z.number().int().min(1).max(500).default(20),
+    staleAfterMs: z.number().int().positive().default(60000),
+    maxAttempts: z.number().int().positive().default(DEFAULT_MAX_ATTEMPTS),
+})
+    .strict();
+function mediaId(ctx) {
+    if (ctx.params.id)
+        return ctx.params.id;
+    return first(ctx.payload.id);
+}
+function attachedVariant(images, variant) {
+    return { size: variant.size, width: variant.width, height: variant.height, format: variant.format, bytes: variant.bytes, state: variant.state, path: images.publicPath(variant.mediaId, variant) };
+}
+const SIZE_SCHEMA = { type: "object", properties: { name: { type: "string" }, width: { type: "number" }, height: { type: ["number", "null"] }, fit: { type: "string", enum: ["inside", "cover"] }, format: { type: "string", enum: ["webp", "original"] }, quality: { type: "number" }, source: { type: "string", enum: ["default", "config", "registered"] }, updatedAt: { type: "number" } }, required: ["name", "width", "fit", "format", "quality", "source", "updatedAt"] };
+const SIZE_INPUT_SCHEMA = { type: "object", properties: { name: { type: "string" }, width: { type: "integer", minimum: 16, maximum: 8192 }, height: { type: "integer", minimum: 16, maximum: 8192 }, fit: { type: "string", enum: ["inside", "cover"] }, format: { type: "string", enum: ["webp", "original"] }, quality: { type: "integer", minimum: 1, maximum: 100 } }, required: ["name", "width"] };
+const VARIANT_SCHEMA = { type: "object", properties: { id: { type: "string" }, mediaId: { type: "string" }, size: { type: "string" }, spec: { type: "string" }, width: { type: "number" }, height: { type: "number" }, format: { type: "string" }, key: { type: "string" }, bytes: { type: "number" }, state: { type: "string", enum: ["pending", "done", "error", "failed"] }, error: { type: ["string", "null"] }, attempts: { type: "number" }, updatedAt: { type: "number" } }, required: ["id", "mediaId", "size", "spec", "width", "height", "format", "key", "bytes", "state", "error", "attempts", "updatedAt"] };
+const JOB_SCHEMA = { type: "object", properties: { id: { type: "string" }, state: { type: "string", enum: ["running", "paused", "done", "error"] }, total: { type: "number" }, done: { type: "number" }, failed: { type: "number" }, cursor: { type: "string" }, startedAt: { type: "number" }, updatedAt: { type: "number" }, finishedAt: { type: ["number", "null"] }, error: { type: ["string", "null"] } }, required: ["id", "state", "total", "done", "failed", "cursor", "startedAt", "updatedAt", "finishedAt", "error"] };
+const ATTACHED_VARIANT_SCHEMA = { type: "object", properties: { size: { type: "string" }, width: { type: "number" }, height: { type: "number" }, format: { type: "string" }, bytes: { type: "number" }, state: { type: "string", enum: ["pending", "done", "error", "failed"] }, path: { type: "string" } }, required: ["size", "width", "height", "format", "bytes", "state", "path"] };
+export default defineModule({
+    name: "images/default",
+    provides: [],
+    requires: [BLOBSTORE, PERSISTENCE],
+    configSchema,
+    async setup(config, deps) {
+        return createImages(config, { blobs: deps.get(BLOBSTORE), db: deps.get(PERSISTENCE), logger: deps.logger });
+    },
+    steps: (images) => ({
+        register: async (ctx) => {
+            const sizes = await images.register(ctx.payload.sizes);
+            if (isErr(sizes))
+                return ctx.fail(sizes.error);
+            return ok({ ...ctx, result: sizes.value });
+        },
+        listSizes: async (ctx) => ok({ ...ctx, result: await images.sizes() }),
+        generate: async (ctx) => {
+            const idsPayload = ctx.payload.ids;
+            if (Array.isArray(idsPayload)) {
+                const items = [];
+                for (const id of idsPayload.filter((value) => typeof value === "string")) {
+                    const known = await images.exists(id);
+                    if (isErr(known))
+                        return ctx.fail(known.error);
+                    if (!known.value)
+                        continue;
+                    const variants = await images.generate(id);
+                    if (isErr(variants))
+                        return ctx.fail(variants.error);
+                    items.push({ id, variants: variants.value });
+                }
+                return ok({ ...ctx, result: { items } });
+            }
+            const id = mediaId(ctx);
+            if (!id)
+                return ctx.fail("VALIDATION", "images: missing media id");
+            const known = await images.exists(id);
+            if (isErr(known))
+                return ctx.fail(known.error);
+            if (!known.value)
+                return ctx.fail("NOT_FOUND", `images: media/${id} not found`);
+            const variants = await images.generate(id);
+            if (isErr(variants))
+                return ctx.fail(variants.error);
+            return ok({ ...ctx, result: { id, variants: variants.value } });
+        },
+        sync: async (ctx) => {
+            const job = await images.sync();
+            if (isErr(job))
+                return ctx.fail(job.error);
+            return ok({ ...ctx, result: job.value });
+        },
+        resume: async (ctx) => {
+            const job = await images.resume();
+            if (isErr(job))
+                return ctx.fail(job.error);
+            return ok({ ...ctx, result: job.value });
+        },
+        prune: async (ctx) => {
+            const names = ctx.payload.sizes;
+            if (!Array.isArray(names) || names.some((name) => typeof name !== "string"))
+                return ctx.fail("VALIDATION", "images: missing sizes");
+            const pruned = await images.prune(names);
+            if (isErr(pruned))
+                return ctx.fail(pruned.error);
+            return ok({ ...ctx, result: pruned.value });
+        },
+        readStatus: async (ctx) => {
+            const status = await images.status();
+            if (isErr(status))
+                return ctx.fail(status.error);
+            return ok({ ...ctx, result: status.value });
+        },
+        remove: async (ctx) => {
+            if (!ctx.params.id)
+                return ctx.fail("VALIDATION", "images: missing id");
+            const removed = await images.remove(ctx.params.id);
+            if (isErr(removed))
+                return ctx.fail(removed.error);
+            return ok(ctx);
+        },
+        removeMany: async (ctx) => {
+            const ids = ctx.result?.ids;
+            if (!Array.isArray(ids))
+                throw new Error("images: removeMany: no ids in result");
+            for (const id of ids) {
+                const removed = await images.remove(id);
+                if (isErr(removed))
+                    return ctx.fail(removed.error);
+            }
+            return ok(ctx);
+        },
+        attach: async (ctx) => {
+            const result = ctx.result;
+            if (typeof result?.id === "string") {
+                const byMedia = await images.variantsOf([result.id]);
+                if (isErr(byMedia))
+                    return ctx.fail(byMedia.error);
+                const variants = byMedia.value.get(result.id) ?? [];
+                return ok({ ...ctx, result: { ...result, variants: variants.map((v) => attachedVariant(images, v)) } });
+            }
+            if (Array.isArray(result?.items)) {
+                const items = result.items;
+                const ids = items.map((item) => item.id).filter((id) => typeof id === "string");
+                const byMedia = await images.variantsOf(ids);
+                if (isErr(byMedia))
+                    return ctx.fail(byMedia.error);
+                const withVariants = items.map((item) => {
+                    const variants = typeof item.id === "string" ? (byMedia.value.get(item.id) ?? []) : [];
+                    return { ...item, variants: variants.map((v) => attachedVariant(images, v)) };
+                });
+                return ok({ ...ctx, result: { ...result, items: withVariants } });
+            }
+            throw new Error("images: attach: no media item(s) in result");
+        },
+        serve: async (ctx) => {
+            const id = ctx.params.id;
+            const file = ctx.params.file;
+            if (!id || !file)
+                return ctx.fail("VALIDATION", "images: missing id or file");
+            const found = await images.read(id, file);
+            if (isErr(found))
+                return ctx.fail(found.error);
+            if (found.value === null) {
+                const failed = await images.failure(id, file);
+                if (isErr(failed))
+                    return ctx.fail(failed.error);
+                if (failed.value)
+                    return ctx.fail("NOT_FOUND", `images: variant ${failed.value.size} for media/${id} failed after ${failed.value.attempts} attempts: ${failed.value.error ?? "unknown error"}`);
+                return ctx.fail("NOT_FOUND", `images: media/${id}/variants/${file} not found`);
+            }
+            const result = binaryResult(found.value.data, found.value.contentType, file);
+            if (found.value.fallback)
+                result.headers = { "x-kestrel-variant": found.value.variant };
+            return ok({ ...ctx, result });
+        },
+        export: stepFactory((dir) => async (ctx) => {
+            const variants = await images.exportTo(dir);
+            if (isErr(variants))
+                return ctx.fail(variants.error);
+            // the step runs after media.export in the same pipeline; replacing ctx.result would drop that
+            // step's counts, so the variant counts are nested under their own key instead.
+            const previous = typeof ctx.result === "object" && ctx.result !== null && !Array.isArray(ctx.result) ? ctx.result : {};
+            return ok({ ...ctx, result: { ...previous, variants: variants.value } });
+        }),
+    }),
+    teardown: (images) => images.close(),
+    describe: () => ({
+        register: { summary: "Replace the sizes registered by this instance – code-declared sizes are held in memory, never stored", reads: [], writes: ["result"], input: { type: "object", properties: { sizes: { type: "array", items: SIZE_INPUT_SCHEMA } }, required: ["sizes"] }, output: { type: "array", items: SIZE_SCHEMA }, errors: { 400: "empty list or invalid size definition", 409: "a size collides with a config size" } },
+        listSizes: { summary: "Effective sizes (defaults/config merged with the sizes registered in this process)", reads: [], writes: ["result"], output: { type: "array", items: SIZE_SCHEMA } },
+        generate: { summary: "Generate variants for one media item (id from params.id or payload.id), or for each id in payload.ids (unknown ids are skipped)", reads: [], writes: ["result"], output: { oneOf: [{ type: "object", properties: { id: { type: "string" }, variants: { type: "array", items: VARIANT_SCHEMA } }, required: ["id", "variants"] }, { type: "object", properties: { items: { type: "array", items: { type: "object", properties: { id: { type: "string" }, variants: { type: "array", items: VARIANT_SCHEMA } }, required: ["id", "variants"] } } }, required: ["items"] }] }, errors: { 400: "missing media id", 404: "media item not found" } },
+        sync: { summary: "Start a sync job, or resume a paused/error/stale one", reads: [], writes: ["result"], output: JOB_SCHEMA, errors: { 409: "a fresh job is already running" } },
+        resume: { summary: "Resume a paused/error/stale job, or no-op (for cron)", reads: [], writes: ["result"], output: { oneOf: [JOB_SCHEMA, { type: "null" }] } },
+        prune: { summary: "Delete the variants of sizes that are no longer declared", reads: [], writes: ["result"], input: { type: "object", properties: { sizes: { type: "array", items: { type: "string" } } }, required: ["sizes"] }, output: { type: "object", properties: { sizes: { type: "number" }, variants: { type: "number" } }, required: ["sizes", "variants"] }, errors: { 400: "missing sizes, or a name is still declared or has no variants" } },
+        readStatus: {
+            summary: "Sizes with usage/variant counts, current job, and sizes whose variants are left over from a size the code no longer declares",
+            reads: [],
+            writes: ["result"],
+            output: {
+                type: "object",
+                properties: {
+                    sizes: { type: "array", items: { type: "object", properties: { ...SIZE_SCHEMA.properties, used: { type: "boolean" }, variants: { type: "object", properties: { done: { type: "number" }, pending: { type: "number" }, error: { type: "number" }, failed: { type: "number" } }, required: ["done", "pending", "error", "failed"] } }, required: [...SIZE_SCHEMA.required, "used", "variants"] } },
+                    job: { oneOf: [JOB_SCHEMA, { type: "null" }] },
+                    orphaned: { type: "object", properties: { sizes: { type: "array", items: { type: "string" } }, variants: { type: "number" } }, required: ["sizes", "variants"] },
+                    registrySeen: { type: "boolean" },
+                },
+                required: ["sizes", "job", "orphaned", "registrySeen"],
+            },
+        },
+        remove: { summary: "Delete one media item's variants (blob + rows)", reads: ["params.id"], writes: [], errors: { 400: "missing id" } },
+        removeMany: { summary: "Delete variants for every id in result.ids (from media.folderItems)", reads: ["result.ids"], writes: [] },
+        attach: { summary: "Add variants[] to a media item or list (result.id or result.items)", reads: ["result"], writes: ["result.variants"], extendsItems: { type: "object", properties: { variants: { type: "array", items: ATTACHED_VARIANT_SCHEMA } }, required: ["variants"] } },
+        serve: { summary: "Binary variant, or the original with x-kestrel-variant: pending while it isn't ready yet", reads: ["params.id", "params.file"], writes: ["result"], binary: true, errors: { 400: "missing id or file", 404: "media item or size not found, or the variant gave up after maxAttempts" } },
+        export: (dir) => ({ summary: `Copy every done variant to ${dir}/<folder>/<filename>.<size>.<ext>`, reads: [], writes: ["result.variants"], extendsOutput: { type: "object", properties: { variants: { type: "object", properties: { written: { type: "number" }, skipped: { type: "number" } }, required: ["written", "skipped"] } }, required: ["variants"] } }),
+    }),
+});

package/dist/sizes.d.ts

@@ -0,0 +1,49 @@
+import { type KestrelError } from "@michaelthielemann/kestrel/errors";
+import { type Result } from "@michaelthielemann/kestrel/result";
+import { z } from "zod";
+export type SizeSource = "default" | "config" | "registered";
+export interface SizeRow extends Size {
+    source: SizeSource;
+    updatedAt: number;
+}
+export declare const DEFAULT_SIZES: Size[];
+export declare const sizeSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodOptional<z.ZodNumber>;
+    fit: z.ZodDefault<z.ZodEnum<["inside", "cover"]>>;
+    format: z.ZodDefault<z.ZodEnum<["webp", "original"]>>;
+    quality: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    width: number;
+    fit: "inside" | "cover";
+    format: "webp" | "original";
+    quality: number;
+    height?: number | undefined;
+}, {
+    name: string;
+    width: number;
+    height?: number | undefined;
+    fit?: "inside" | "cover" | undefined;
+    format?: "webp" | "original" | undefined;
+    quality?: number | undefined;
+}>, {
+    name: string;
+    width: number;
+    fit: "inside" | "cover";
+    format: "webp" | "original";
+    quality: number;
+    height?: number | undefined;
+}, {
+    name: string;
+    width: number;
+    height?: number | undefined;
+    fit?: "inside" | "cover" | undefined;
+    format?: "webp" | "original" | undefined;
+    quality?: number | undefined;
+}>;
+export type Size = z.output<typeof sizeSchema>;
+export declare function spec(size: Size): string;
+export declare function extOf(size: Size, originalFormat: string): string;
+export declare function mergeSizes(base: Size[], baseSource: "default" | "config", registered: Size[]): Result<SizeRow[], KestrelError<"CONFLICT">>;

package/dist/sizes.js

@@ -0,0 +1,47 @@
+import { failure } from "@michaelthielemann/kestrel/errors";
+import { err, ok } from "@michaelthielemann/kestrel/result";
+import { z } from "zod";
+export const DEFAULT_SIZES = [
+    { name: "thumb", width: 320, fit: "inside", format: "webp", quality: 82 },
+    { name: "small", width: 640, fit: "inside", format: "webp", quality: 82 },
+    { name: "medium", width: 1024, fit: "inside", format: "webp", quality: 82 },
+    { name: "large", width: 1600, fit: "inside", format: "webp", quality: 82 },
+    { name: "xl", width: 2400, fit: "inside", format: "webp", quality: 82 },
+];
+export const sizeSchema = z
+    .object({
+    name: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    width: z.number().int().min(16).max(8192),
+    height: z.number().int().min(16).max(8192).optional(),
+    fit: z.enum(["inside", "cover"]).default("inside"),
+    format: z.enum(["webp", "original"]).default("webp"),
+    quality: z.number().int().min(1).max(100).default(82),
+})
+    .superRefine((size, ctx) => {
+    if (size.fit === "cover" && size.height === undefined) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "height is required for fit \"cover\"", path: ["height"] });
+    }
+});
+export function spec(size) {
+    return `${size.width}x${size.height ?? ""}:${size.fit}:${size.format}:${size.quality}`;
+}
+const EXT_ALIASES = { jpeg: "jpg" };
+export function extOf(size, originalFormat) {
+    if (size.format === "webp")
+        return "webp";
+    return EXT_ALIASES[originalFormat] ?? originalFormat;
+}
+export function mergeSizes(base, baseSource, registered) {
+    const now = Date.now();
+    const rows = new Map();
+    for (const size of base)
+        rows.set(size.name, { ...size, source: baseSource, updatedAt: now });
+    for (const size of registered) {
+        const existing = rows.get(size.name);
+        if (baseSource === "config" && existing?.source === "config" && spec(existing) !== spec(size)) {
+            return err(failure("CONFLICT", `images: size "${size.name}" is defined in config`));
+        }
+        rows.set(size.name, { ...size, source: "registered", updatedAt: now });
+    }
+    return ok([...rows.values()]);
+}