@cosmicdrift/kumiko-types 0.304.0 → 0.306.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.304.0",
+  "version": "0.306.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>",
@@ -34,6 +34,10 @@
       "types": "./src/event-type-map.ts",
       "default": "./src/event-type-map.ts"
     },
+    "./extension-options-map": {
+      "types": "./src/extension-options-map.ts",
+      "default": "./src/extension-options-map.ts"
+    },
     "./http-route": {
       "types": "./src/http-route.ts",
       "default": "./src/http-route.ts"

package/src/config.ts

@@ -358,6 +358,14 @@ export type JobTrigger =
   | { readonly cron: string }
   | { readonly manual: true };
 
+export type JobBackoffStrategy = "fixed" | "exponential";
+// String form uses the framework's default base delay; the object form's
+// `delayMs` is the base BullMQ multiplies: "fixed" keeps it constant,
+// "exponential" scales it delayMs * 2^(attemptsMade-1) per retry.
+export type JobBackoff =
+  | JobBackoffStrategy
+  | { readonly type: JobBackoffStrategy; readonly delayMs?: number | undefined };
+
 export type JobDefinition = {
   readonly name: string;
   readonly handler: JobHandlerFn;
@@ -366,14 +374,16 @@ export type JobDefinition = {
   readonly maxPerTenant?: number | undefined;
   readonly debounceMs?: number | undefined;
   readonly retries?: number | undefined;
-  readonly backoff?: "fixed" | "exponential" | undefined;
+  readonly backoff?: JobBackoff | undefined;
   readonly timeout?: number | undefined;
   readonly schema?: ZodType | undefined;
   // Enqueue this job once when a runner for its lane starts. Fire-and-forget:
   // the enqueue is awaited, the run is not, so a throwing handler only fails
   // the queue job — the process keeps booting and reports ready.
-  // Deduped on a fixed job id, so it runs at most once per Redis dataset: a
-  // boot job that already ran (or failed) is not retried on a later deploy.
+  // Deduped via a persistent per-queue marker set at enqueue time (not the
+  // fixed job id alone, which BullMQ's bounded retention can evict), so it
+  // runs at most once per Redis dataset: a boot job that already ran (or
+  // failed) is not retried on a later deploy.
   // Never a deploy gate — use `bootGate` for that.
   readonly runOnBoot?: boolean | undefined;
   // Run this job inline while the runner for its lane starts, before cron

package/src/extension-options-map.ts

@@ -0,0 +1,21 @@
+// Cross-Feature Compile-Time-Type-Map for `r.useExtension(name, entity, options)`.
+// Augmented per extension point via `declare module "@cosmicdrift/kumiko-framework/engine"`,
+// mirroring event-type-map.ts; names without augmentation stay untyped.
+
+import type { EscapeHatchDeclaration } from "./handlers";
+
+// MUST be `interface` (not `type`): only interfaces support TS declaration-
+// merging. See event-type-map.ts for the same constraint.
+
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker — augmented per extension point
+export interface KumikoExtensionOptionsMap {}
+
+/** Options shape for an extension name: the augmented hook shape plus `escapeHatch`, or an untyped bag if unaugmented. */
+export type ExtensionOptionsFor<N extends string> = N extends keyof KumikoExtensionOptionsMap
+  ? KumikoExtensionOptionsMap[N] & { readonly escapeHatch?: EscapeHatchDeclaration }
+  : Record<string, unknown>;
+
+/** Rest-tuple for useExtension's positional options arg: required for an augmented name, optional otherwise. */
+export type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap
+  ? [options: ExtensionOptionsFor<N>]
+  : [options?: Record<string, unknown>];

package/src/feature.ts

@@ -24,6 +24,7 @@ import type {
 } from "./define-handler";
 import type { RegisterEntityCrudOptions } from "./entity-handlers";
 import type { EntityTableMeta } from "./entity-table-meta-types";
+import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map";
 import type { EntityDefinition } from "./fields";
 import type {
   AccessRule,
@@ -653,9 +654,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
 
   extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
 
-  useExtension(extensionName: string, entity: NameOrRef, options?: Record<string, unknown>): void;
-  useExtension(
-    definition: { readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>,
+  useExtension<N extends string>(
+    extensionName: N,
+    entity: NameOrRef,
+    ...options: ExtensionOptionsArgs<N>
+  ): void;
+  useExtension<N extends string>(
+    definition: { readonly name: N; readonly entity: NameOrRef } & ExtensionOptionsFor<N>,
   ): void;
 
   /**

package/src/fields.ts

@@ -836,6 +836,38 @@ export type FieldDefinition =
   | FilesFieldDef
   | ImagesFieldDef;
 
+// Exhaustive catalogue of `FieldDefinition["type"]` values, derived from a
+// `Record` so an added/removed union member fails to compile here instead of
+// silently drifting out of sync with the runtime validator that consults
+// this list (feature-ast's pattern-change-schema). Plain array, not a Set —
+// same rationale as NO_WIDGET_FIELD_TYPES (guard-types-class-free.test.ts).
+const FIELD_TYPE_NAME_FLAGS: Record<FieldDefinition["type"], true> = {
+  text: true,
+  longText: true,
+  boolean: true,
+  select: true,
+  multiSelect: true,
+  number: true,
+  bigInt: true,
+  decimal: true,
+  money: true,
+  reference: true,
+  embedded: true,
+  jsonb: true,
+  date: true,
+  timestamp: true,
+  tz: true,
+  locatedTimestamp: true,
+  file: true,
+  image: true,
+  files: true,
+  images: true,
+};
+
+export const FIELD_TYPE_NAMES: readonly FieldDefinition["type"][] = Object.keys(
+  FIELD_TYPE_NAME_FLAGS,
+) as FieldDefinition["type"][];
+
 /** FieldDefinition as an entity-less inline form screen (actionForm,
  *  secretMint) may declare it: a `money` field there has no entity to borrow
  *  `defaultCurrency` from, so it must name its own currency source, or the

package/src/tenant-db-types.ts

@@ -108,7 +108,7 @@ export type UncheckedSystemDb = {
   // durability writes that must survive a rollback of the handler's own
   // transaction. Throws if the dispatch has no outside-transaction source
   // configured (e.g. a hand-built UncheckedSystemDb that only ever passed
-  // the in-tx db to createUncheckedSystemDb).
+  // the in-tx db, as createSystemDbView callers do).
   readonly outsideTransaction: {
     assertTenantMatch(tenantId: TenantId): TenantDb;
     acknowledgeCrossTenant(reason: string): TenantDb;