@cosmicdrift/kumiko-types 0.189.0 → 0.190.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.189.0",
+  "version": "0.190.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -194,6 +194,10 @@
       "types": "./src/file-provider-resolver-types.ts",
       "default": "./src/file-provider-resolver-types.ts"
     },
+    "./derivatives-types": {
+      "types": "./src/derivatives-types.ts",
+      "default": "./src/derivatives-types.ts"
+    },
     "./event-store-executor-types": {
       "types": "./src/event-store-executor-types.ts",
       "default": "./src/event-store-executor-types.ts"

package/src/derivatives-types.ts

@@ -0,0 +1,51 @@
+// Derived-file-variants (thumbnails, resized/reformatted images, …) — pure
+// types, no runtime logic. Client-visible package: no `node:*` imports.
+
+export type VariantFit = "cover" | "inside" | "contain";
+export type VariantFormat = "webp" | "avif" | "jpeg";
+
+export type VariantSpec = {
+  // Default "inside" when omitted (renderer-side default, Schnitt 2).
+  readonly fit?: VariantFit;
+  readonly size?: { readonly width: number; readonly height: number };
+  // Alternative to `size` — longest edge in pixels, aspect preserved.
+  readonly maxEdge?: number;
+  readonly format?: VariantFormat;
+  readonly quality?: number;
+  // Whole-image blur radius.
+  readonly blur?: number;
+};
+
+// A renderer turns the original bytes + a spec into the derived bytes for one
+// variant. Registered per MIME-type (exact or `<type>/*` wildcard) via the
+// `derivativeRenderer` extension point — see EXT_DERIVATIVE_RENDERER.
+//
+// The renderer must produce `spec.format` when set, and the source's own
+// format otherwise. It never reports back what it produced: the caller
+// derives the output mimeType from the spec alone (see outputMimeType in
+// derivatives-context.ts), because a cache hit has no renderer run to read
+// a mimeType off, and a spec-derived value is the only one both branches
+// can share.
+export type DerivativeRendererPlugin = {
+  readonly render: (
+    input: Uint8Array,
+    spec: VariantSpec,
+    sourceMimeType: string,
+  ) => Promise<Uint8Array>;
+};
+
+export type VariantResult = {
+  readonly storageKey: string;
+  readonly mimeType: string;
+  // true = rendered during this call, false = an existing derivative was
+  // found and returned unchanged.
+  readonly rendered: boolean;
+};
+
+// The `ctx.derivatives` service — derive-on-first-use variants of a tracked
+// FileRef. `name` feeds only the readable key-prefix; `spec` determines the
+// content hash, so a spec change always produces a fresh URL instead of
+// silently overwriting what's cached under the old pixels.
+export type DerivativesContext = {
+  readonly variant: (fileRefId: string, spec: VariantSpec, name: string) => Promise<VariantResult>;
+};

package/src/handlers.ts

@@ -2,6 +2,7 @@ import type { Redis } from "ioredis";
 import type { ZodType } from "zod";
 import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config";
 import type { DbConnection } from "./db-connection";
+import type { DerivativesContext } from "./derivatives-types";
 import type { EntityCache } from "./entity-cache";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type { FileContext } from "./file-handle-types";
@@ -239,6 +240,9 @@ type SharedContextFields = {
   // GDPR jobs all resolve through the same file-foundation provider. Hooks/
   // handlers use ctx.files.ref(key) instead of receiving binaries in payloads.
   readonly files?: FileContext;
+  // Derive-on-first-use variants (thumbnails, resized/reformatted images) of a
+  // tracked FileRef. Present whenever `files` resolves — see files above.
+  readonly derivatives?: DerivativesContext;
   // Boot-built, per-tenant file-provider resolver. Set by buildServer when a
   // `file-provider-*` plugin is mounted; the dispatcher reads it to materialise
   // ctx.files (and the upload routes + MSP-applies use the same resolver).

package/src/multi-stream-apply-context-types.ts

@@ -1,3 +1,4 @@
+import type { DerivativesContext } from "./derivatives-types";
 import type { StoredEvent } from "./event-store-types";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type { FileContext } from "./file-handle-types";
@@ -35,4 +36,7 @@ export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> =
   // `ctx.files.ref(payload.storageKey).read()` and write derivates via
   // `.derive("thumb").write(...)` — binaries never ride through events.
   readonly files?: FileContext;
+  // Derive-on-first-use variants, mirrors AppContext.derivatives. Present
+  // exactly when `files` is — same file-foundation-provider precondition.
+  readonly derivatives?: DerivativesContext;
 };