@cosmicdrift/kumiko-types 0.188.0 → 0.190.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.188.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/entity-table-meta-types.ts

@@ -21,6 +21,10 @@ export type PgType =
   | "jsonb"
   | "timestamptz"
   | "timestamptz(3)"
+  // Calendar day, no time-of-day/timezone component — Temporal.PlainDate.
+  // Distinct from timestamptz: a `date` field is a pure calendar concept
+  // (invoice date, lease term) and must never round-trip through an Instant.
+  | "date"
   // Exact decimal — precision/scale are encoded in the type string so the
   // DDL renderer and read-coercion need no side-channel metadata.
   | `numeric(${number},${number})`;

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;
 };

package/src/screen.ts

@@ -593,6 +593,22 @@ export type EntityEditScreenDefinition = {
    *  (History-/Audit-Erhalt): unterdrückt den Löschen-Button im
    *  Update-Form. */
   readonly allowDelete?: boolean;
+  /** Default false. `true` for singleton entities (exactly one record per
+   *  tenant: organization, settings, tenant profile). A call without an
+   *  `entityId` first resolves the existing record via `<entity>:list`
+   *  (limit 1) and renders the update branch with prefill on a hit,
+   *  instead of blindly creating another one. The create branch only
+   *  fires when the table is empty (and `allowCreate: false` still
+   *  applies there). */
+  readonly singleton?: boolean;
+  /** Navigate to this screen ID after a successful save (create or update).
+   *  Either a same-feature short screen-ID, or a fully-qualified
+   *  cross-feature screen QN (`<feature>:screen:<id>`) — the nav-router
+   *  resolves both against the schema; boot-validator checks the target
+   *  resolves to a registered screen. Overrides the default post-save
+   *  target (the entity's list screen); delete is unaffected and still
+   *  always navigates to the list. */
+  readonly redirect?: string;
   /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key), überschreibt
    *  die Default-Konvention `<feature>:entity:<entity>:field:<name>`.
    *  Primär für configEdit: dessen Pseudo-Entity `__config-edit__` hat
@@ -639,18 +655,20 @@ export type ActionFormScreenDefinition = {
   /** i18n-key für den Submit-Button. Default: i18n-Default des
    *  Renderers (typischerweise "actions.submit"). */
   readonly submitLabel?: string;
-  /** Nach erfolgreichem Submit zu dieser Screen-ID navigieren (kurze
-   *  ID, z.B. "item-list" — gleiche Feature, der nav-Router resolved
-   *  zum vollen Pfad). Cross-Feature-Redirect ist nicht supported.
-   *  Wenn nicht gesetzt, bleibt der User auf dem Form-Screen. Boot-
-   *  Validator prüft dass die ID einen registrierten Screen meint. */
+  /** Nach erfolgreichem Submit zu dieser Screen-ID navigieren: entweder
+   *  kurze ID (z.B. "item-list" — gleiche Feature, der nav-Router
+   *  resolved zum vollen Pfad) oder voll-qualifizierte Cross-Feature-QN
+   *  (`<feature>:screen:<id>`). Wenn nicht gesetzt, bleibt der User auf
+   *  dem Form-Screen. Boot-Validator prüft dass das Ziel einen
+   *  registrierten Screen meint. */
   readonly redirect?: string;
   /** Ziel des Abbrechen-Buttons. Default: `redirect` (historisches
    *  Verhalten — Cancel und Submit-Redirect landen dann am selben Ort).
    *  `false` = kein Abbrechen-Button; richtig für Single-Action-Screens
    *  ohne verwerfbaren Zustand (z.B. "Test-Mail senden"), wo Abbrechen
-   *  nur ein zweiter Weg zum selben Ziel wäre. Boot-Validator prüft
-   *  String-Targets wie `redirect`. */
+   *  nur ein zweiter Weg zum selben Ziel wäre. Akzeptiert dieselben
+   *  String-Targets wie `redirect` (kurze ID oder Cross-Feature-QN);
+   *  Boot-Validator prüft das. */
   readonly cancelTarget?: string | false;
   readonly slots?: ScreenSlots;
   readonly access?: AccessRule;