@cosmicdrift/kumiko-types 0.362.0 → 0.364.0

package/dist/cache-sync-types.d.ts

@@ -1,5 +1,8 @@
+export type CacheSyncPublishOptions = {
+    readonly remoteOnly?: boolean;
+};
 export type CacheSyncBus = {
-    publish(topic: string, message: unknown): void;
+    publish(topic: string, message: unknown, options?: CacheSyncPublishOptions): void;
     subscribe(topic: string, listener: (message: unknown) => void): () => void;
     onResync(listener: () => void): () => void;
 };

package/dist/config.d.ts

@@ -30,7 +30,7 @@ export type ConfigValidateContext = {
     readonly scope: ConfigScope;
     readonly tenantId: TenantId;
     readonly userId: string | null;
-    readonly db: DbConnection | TenantDb;
+    readonly db: TenantDb;
 };
 export type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
 export type ConfigBacking = "config" | "secrets";
@@ -183,14 +183,67 @@ export type NotificationRecipientFn = (result: import("./hooks.js").SaveContext)
 } | null;
 export type NotificationDataFn = (result: import("./hooks.js").SaveContext) => Record<string, unknown>;
 export type NotificationTemplateFn = (data: Record<string, unknown>) => Record<string, unknown>;
+type TemplateVariableCommon = {
+    readonly label?: string;
+    readonly required?: boolean;
+};
+export type TemplateScalarVariableDef = (TemplateVariableCommon & {
+    readonly type: "text";
+    readonly example?: string;
+}) | (TemplateVariableCommon & {
+    readonly type: "link";
+    readonly example?: string;
+}) | (TemplateVariableCommon & {
+    readonly type: "richText";
+    readonly example?: string;
+}) | (TemplateVariableCommon & {
+    readonly type: "money";
+    readonly example?: number | {
+        readonly amount: number;
+        readonly currency: string;
+    };
+}) | (TemplateVariableCommon & {
+    readonly type: "date";
+    readonly example?: string;
+});
+export type TemplateListVariableDef = TemplateVariableCommon & {
+    readonly type: "list";
+    readonly item: Readonly<Record<string, TemplateScalarVariableDef>>;
+    readonly example?: readonly Readonly<Record<string, unknown>>[];
+};
+export type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef;
+export type TemplateVariables = Readonly<Record<string, TemplateVariableDef>>;
+export type NotificationTemplateMeta = {
+    readonly subject: string;
+    readonly previewText?: string;
+    readonly layoutSlug?: string;
+    readonly category?: "transactional" | "marketing";
+    readonly sender?: string;
+};
+export type NotificationTemplateBody = {
+    readonly body: string;
+};
+export type NotificationLocalizedTemplate = Readonly<Record<string, {
+    readonly body: string;
+    readonly meta: NotificationTemplateMeta;
+}>>;
+export type NotificationRecordMapping = {
+    readonly entity: string;
+    readonly map: Readonly<Record<string, string>>;
+};
 export type NotificationDefinition = {
     readonly name: string;
-    readonly trigger: {
+    readonly trigger?: {
         readonly on: string;
     };
-    readonly recipient: NotificationRecipientFn;
-    readonly data: NotificationDataFn;
+    readonly recipient?: NotificationRecipientFn;
+    readonly data?: NotificationDataFn;
     readonly templates: Readonly<Record<string, NotificationTemplateFn>> | undefined;
+    readonly variables?: TemplateVariables;
+    readonly record?: NotificationRecordMapping;
+    readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+    readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+    readonly localizedTemplate?: () => NotificationLocalizedTemplate;
 };
 export type PluralForms = {
     readonly zero?: string;
@@ -259,3 +312,4 @@ export type CreateUserSeedOptions = {
     readonly tenantId: string;
     readonly userId: string;
 };
+export {};

package/dist/define-handler.d.ts

@@ -1,9 +1,9 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
 import type { KumikoEventTypeMap } from "./event-type-map.js";
-import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, PreTransactionReservation, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
+import type { AccessRule, AgentHandlerHints, BeforeTransactionPhase, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, PreparedWriteEvent, PreTransactionReservation, QueryEvent, RateLimitDeclaration, WriteHandlerTransactionMode, WriteResult } from "./handlers.js";
 import type { PipelineDef } from "./step.js";
-export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
+export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined> = {
     readonly name: TName;
     readonly schema: TSchema;
     readonly access: AccessRule;
@@ -16,11 +16,13 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
+    readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
     readonly tenantlessAnonymous?: boolean;
-    readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+    readonly transaction?: WriteHandlerTransactionMode;
+    readonly handler: (event: PreparedWriteEvent<z.infer<TSchema>, TPrepared>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
 };
-export type WriteHandlerInput<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
+export type WriteHandlerInput<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined> = {
     readonly name: TName;
     readonly schema: TSchema;
     readonly access: AccessRule;
@@ -31,9 +33,11 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
+    readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
     readonly tenantlessAnonymous?: boolean;
+    readonly transaction?: WriteHandlerTransactionMode;
 } & ({
-    readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+    readonly handler: (event: PreparedWriteEvent<z.infer<TSchema>, TPrepared>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: never;
 } | {
     readonly perform: PipelineDef<z.infer<TSchema>, TData>;

package/dist/feature.d.ts

@@ -1,9 +1,10 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
-import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys, TranslationsDef } from "./config.js";
+import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TemplateVariables, TranslationKeys, TranslationsDef } from "./config.js";
 import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { EntityTableMeta } from "./entity-table-meta-types.js";
+import type { KumikoEventTypeMap } from "./event-type-map.js";
 import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.js";
 import type { EntityDefinition } from "./fields.js";
 import type { AccessRule, AgentHandlerHints, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, PayloadRateLimitOption, QualifiedEventName, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef, WriteHandlerFn } from "./handlers.js";
@@ -234,7 +235,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
         readonly name: string;
     } & EntityDefinition): EntityRef;
     crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
-    writeHandler<TName extends string, TSchema extends ZodType>(def: WriteHandlerDefinition<TName, TSchema>): HandlerRef;
+    writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
     writeHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: WriteHandlerFn<z.infer<TSchema>>, options: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
@@ -296,21 +297,31 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
     job(definition: JobDefinition): void;
     notification(name: string, definition: {
-        readonly trigger: {
+        readonly trigger?: {
             readonly on: NameOrRef;
         };
-        readonly recipient: NotificationRecipientFn;
-        readonly data: NotificationDataFn;
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
         readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
     }): void;
     notification(definition: {
         readonly name: string;
-        readonly trigger: {
+        readonly trigger?: {
             readonly on: NameOrRef;
         };
-        readonly recipient: NotificationRecipientFn;
-        readonly data: NotificationDataFn;
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
         readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: {

package/dist/fields.d.ts

@@ -750,7 +750,8 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
     readonly systemStream?: boolean;
     /** Schema version stamped on every lifecycle event (default 1, integer 1..999). Bump it together with a step in `eventMigrations`. */
     readonly eventVersion?: number;
-    /** One step per version, fromVersion → fromVersion+1. Transforms run on row-shaped field records; the record may be partial, touch only keys that are present. */
+    /** One step per version, fromVersion → fromVersion+1. Transforms run on row-shaped field records; the record may be partial, touch only keys that are present.
+     *  `pii` and `encrypted` fields arrive as stored ciphertext bound to their field name (AAD): pass them through under the same key, never rename or derive from them, or the value can no longer be decrypted. */
     readonly eventMigrations?: readonly EntityEventMigration[];
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;

package/dist/file-handle-types.d.ts

@@ -8,5 +8,8 @@ export type FileHandle = {
 };
 export type FileContext = {
     ref(key: string): FileHandle;
+    refFromFileRef(row: {
+        readonly storageKey: string;
+    }): FileHandle;
     list(prefix: string): Promise<readonly string[]>;
 };

package/dist/handlers.d.ts

@@ -101,6 +101,12 @@ export type WriteEvent<TPayload = unknown> = {
     readonly payload: TPayload;
     readonly user: SessionUser;
 };
+/** What a handler sees when its `beforeTransaction` phase ran: the phase's `data` as `prepared`; absent for handlers without the phase. */
+export type PreparedWriteEvent<TPayload = unknown, TPrepared = unknown> = WriteEvent<TPayload> & ([TPrepared] extends [undefined] ? {
+    readonly prepared?: undefined;
+} : {
+    readonly prepared: TPrepared;
+});
 export type QueryEvent<TPayload = unknown> = {
     readonly type: string;
     readonly payload: TPayload;
@@ -157,16 +163,26 @@ export type NotifyDelivery = {
     readonly confirmed?: false;
     readonly deliveryAttemptId?: string;
 };
-export type NotifyResult = {
+export type NotifyDispatched = {
+    readonly kind: "dispatched";
     readonly deliveries: readonly NotifyDelivery[];
 };
-export type NotifyFn = (notificationType: string, options: NotifyOptions) => Promise<NotifyResult>;
+export type NotifyDeferred = {
+    readonly kind: "deferred";
+};
+export type NotifyResult = NotifyDispatched | NotifyDeferred;
+export type NotifyFn = {
+    (notificationType: string, options: NotifyOptions & {
+        readonly immediate: true;
+    }): Promise<NotifyDispatched>;
+    (notificationType: string, options: NotifyOptions): Promise<NotifyResult>;
+};
 export type NotifyJobDispatcher = {
     dispatch(jobName: string, payload: Record<string, unknown>, meta?: {
         readonly priority?: number;
     }): Promise<unknown>;
 };
-export type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher) => NotifyFn;
+export type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher, deliveryDb?: DbConnection, fileProviderResolver?: FileProviderResolver) => NotifyFn;
 export type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants" | "cross-tenant-read";
 export type EscapeHatchTarget = {
     readonly id: string;
@@ -221,6 +237,7 @@ type SharedContextFields = {
     readonly entityCache?: EntityCache;
     readonly notify?: NotifyFn;
     readonly _notifyFactory?: NotifyFactory;
+    readonly _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
     readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly secrets?: import("./secrets-types.js").SecretsContext;
     readonly masterKeyProvider?: import("./secrets-types.js").MasterKeyProvider;
@@ -288,6 +305,11 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     } | null;
     readonly _userId?: string | undefined;
     readonly _handlerType?: string | undefined;
+    /** Keyed digest for handler-owned rate-limit keys, so Redis never holds a
+     *  plaintext or plainly hashed identifier. Scoped to the running handler:
+     *  the same input yields a different digest per handler and never matches a
+     *  dispatcher payload-bucket digest. Absent when the app wires no digest key. */
+    readonly rateLimitDigest?: (value: string) => string;
     readonly includeDeleted?: boolean;
     readonly runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
     readonly query: (qn: string, payload: unknown) => Promise<unknown>;
@@ -496,11 +518,13 @@ export type RateLimitOption = {
 export type RateLimitPayloadBucket = {
     readonly payloadField: string;
 };
+export type PayloadBucketNormalization = "email";
 export type PayloadRateLimitOption = {
     readonly per: RateLimitPayloadBucket;
     readonly limit: number;
     readonly windowSeconds: number;
     readonly cost?: number;
+    readonly normalize?: PayloadBucketNormalization;
 };
 export type RateLimitDisabled = {
     readonly disabled: true;
@@ -541,6 +565,15 @@ export type ReservationHandle = {
  *  The returned release (or handle.release) runs when the transaction does not commit (failure
  *  result, throw, rollback, failed commit). Throwing a KumikoError rejects the write. */
 export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
+/** Outcome of a write handler's pre-transaction phase. `release` runs when the handler transaction does not commit (failure result, throw, rollback, failed commit with unknown outcome), so it must itself tolerate a commit that actually happened. */
+export type BeforeTransactionResult<TPrepared = unknown> = {
+    readonly isSuccess: true;
+    readonly data: TPrepared;
+    readonly release?: ReservationRelease;
+} | WriteFailure;
+export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: HandlerContext) => Promise<BeforeTransactionResult<TPrepared>>;
+/** `perCommand`: the handler runs without a transaction of its own. */
+export type WriteHandlerTransactionMode = "perCommand";
 export type WriteHandlerDef = {
     readonly name: string;
     readonly schema: ZodType;
@@ -560,6 +593,16 @@ export type WriteHandlerDef = {
     /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */
     readonly reserveBeforeTransaction?: PreTransactionReservation;
+    /** Runs after all pre-handler gates (and after reserveBeforeTransaction) and before the
+     *  transaction opens: no transaction and no connection held, for external I/O and reads only.
+     *  Its `data` reaches the handler as `event.prepared`; a failure result or throw rejects the
+     *  write before anything is written. A handler with this phase cannot run as a nested ctx.write. */
+    readonly beforeTransaction?: BeforeTransactionPhase;
+    /** `"perCommand"`: the handler runs without a transaction of its own. Every ctx.write/writeAs it
+     *  issues runs as its own top-level command with its own transaction and afterCommit hooks;
+     *  ctx.db writes and event appends throw. It cannot run as a nested write or inside a
+     *  multi-command batch, and cannot be combined with beforeTransaction/reserveBeforeTransaction. */
+    readonly transaction?: WriteHandlerTransactionMode;
     /** Lets an anonymous `POST /api/write` for this handler proceed under
      *  SYSTEM_TENANT_ID when the host resolves no tenant. Boot requires
      *  `access.roles: ["anonymous"]` and a real `rateLimit`. */

package/dist/hooks.d.ts

@@ -23,6 +23,7 @@ export type DeleteContext = {
     readonly data: Readonly<Record<string, unknown>>;
     readonly entityName?: string | undefined;
     readonly event?: StoredEvent | undefined;
+    readonly lockGuardBypassed?: boolean | undefined;
 };
 export type LifecycleResult = SaveContext | DeleteContext;
 export type PreSaveHookFn = (changes: Record<string, unknown>, context: AppContext & {

package/dist/kms-adapter-types.js

@@ -34,7 +34,7 @@ export function subjectIdFromKey(key) {
     if (key.startsWith("user:"))
         return { kind: "user", userId: key.slice("user:".length) };
     if (key.startsWith("tenant:")) {
-        return { kind: "tenant", tenantId: key.slice("tenant:".length) }; // @cast-boundary parse of a key this module minted
+        return { kind: "tenant", tenantId: key.slice("tenant:".length) };
     }
     if (key.startsWith("record:")) {
         const rest = key.slice("record:".length);

package/dist/nav.d.ts

@@ -18,7 +18,7 @@ export type NavDefinition = {
     readonly workspaces?: readonly string[];
 };
 /** Client editor format for r.contentCollection() — not template body storage formats. */
-export type ContentEditorFormat = "plain" | "rich" | "markdown";
+export type ContentEditorFormat = "plain" | "rich" | "markdown" | "document";
 export type ContentCollectionDefinition = {
     readonly id: string;
     readonly kind: string;

package/dist/screen.d.ts

@@ -554,8 +554,10 @@ export type ProjectionListScreenDefinition = {
      *  boot-validator only checks structure (`op:"in"` ⇒ array value). */
     readonly filter?: ScreenFilter;
     /** User-toggleable facet dropdowns — see `ListFacetSpec` doc. `field`
-     *  must be a declared column; the bound query handler must accept
-     *  `filters` in its Zod schema — the boot-validator checks both. A
+     *  must be a declared column, except for `type: "reference"`: it filters
+     *  by id through the bound query's `filters` and needs a registered
+     *  `entity` instead. The bound query handler must accept `filters` in its
+     *  Zod schema — the boot-validator checks both. A
      *  "dateRange" facet instead needs its two `params` keys in that schema;
      *  it sends no `filters` entry. */
     readonly facets?: readonly ListFacetSpec[];
@@ -1144,7 +1146,9 @@ export type EditRelatedListSection = {
     readonly searchable?: boolean;
     /** User-toggleable facet dropdowns — same explicit-label `ListFacetSpec` as
      *  `projectionList.facets` (a relatedList has no entity to derive filterable
-     *  fields from). `field` must be a declared column and the bound query
+     *  fields from). `field` must be a declared column, except for
+     *  `type: "reference"`: it filters by id through the bound query's
+     *  `filters` and needs a registered `entity` instead. The bound query
      *  handler must accept `filters` in its Zod schema — the boot-validator
      *  checks both. Selected values ride along as `payload.filters`. */
     readonly facets?: readonly ListFacetSpec[];

package/dist/secrets-types.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
+import type { DbRunner } from "./db-connection.js";
 import type { TenantId } from "./identifiers.js";
 declare const SecretBrand: unique symbol;
 export type Secret<T = string> = {
@@ -21,6 +22,7 @@ export type SecretKeyRef = string | {
     readonly name: string;
 };
 export interface SecretsContext {
+    withRunner(runner: DbRunner): SecretsContext;
     get(tenantId: TenantId, key: SecretKeyRef, auditCtx?: SecretAuditContext): Promise<Secret<string> | undefined>;
     has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
     set(tenantId: TenantId, key: SecretKeyRef, value: string, opts?: {

package/dist/type-guards.d.ts

@@ -0,0 +1,8 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Membership test that narrows `candidate` to the element union of a const tuple. */
+export declare function isOneOf<const T extends readonly unknown[]>(values: T, candidate: unknown): candidate is T[number];
+/** Reads a string `code` (e.g. Node `ErrnoException`, Postgres SQLSTATE) off an unknown thrown value. */
+export declare function errorCodeOf(error: unknown): string | undefined;
+/** Reads one property off an unknown value (object or function); undefined for primitives, null and absent keys. */
+export declare function propertyOf(value: unknown, key: PropertyKey): unknown;

package/dist/type-guards.js

@@ -0,0 +1,21 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Membership test that narrows `candidate` to the element union of a const tuple. */
+export function isOneOf(values, candidate) {
+    return values.some((value) => value === candidate);
+}
+/** Reads a string `code` (e.g. Node `ErrnoException`, Postgres SQLSTATE) off an unknown thrown value. */
+export function errorCodeOf(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return undefined;
+    return typeof error.code === "string" ? error.code : undefined;
+}
+/** Reads one property off an unknown value (object or function); undefined for primitives, null and absent keys. */
+export function propertyOf(value, key) {
+    if ((typeof value !== "object" && typeof value !== "function") || value === null) {
+        return undefined;
+    }
+    return Reflect.get(value, key);
+}

package/dist/write-error-info-types.d.ts

@@ -5,6 +5,7 @@ export type WriteErrorInfo = {
     readonly i18nParams?: Readonly<Record<string, unknown>>;
     readonly message: string;
     readonly details?: unknown;
+    readonly retryAfterSeconds?: number;
 };
 export type WriteFailure = {
     readonly isSuccess: false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.362.0",
+  "version": "0.364.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>",
@@ -26,6 +26,10 @@
       "types": "./dist/identifiers.d.ts",
       "default": "./dist/identifiers.js"
     },
+    "./type-guards": {
+      "types": "./dist/type-guards.d.ts",
+      "default": "./dist/type-guards.js"
+    },
     "./session-cookies": {
       "types": "./dist/session-cookies.d.ts",
       "default": "./dist/session-cookies.js"
@@ -297,6 +301,10 @@
         "types": "./dist/identifiers.d.ts",
         "default": "./dist/identifiers.js"
       },
+      "./type-guards": {
+        "types": "./dist/type-guards.d.ts",
+        "default": "./dist/type-guards.js"
+      },
       "./session-cookies": {
         "types": "./dist/session-cookies.d.ts",
         "default": "./dist/session-cookies.js"