@cosmicdrift/kumiko-types 0.395.0 → 0.397.0

package/dist/event-store-executor-types.d.ts

@@ -9,6 +9,9 @@ import type { TenantDb } from "./tenant-db-types.ts";
 export type ParentVisibilityOption = {
     readonly entities: ReadonlyMap<string, EntityDefinition>;
 };
+export type ParentVisibilityGateOption = {
+    readonly parentVisibility?: ParentVisibilityOption;
+};
 export type PreSaveRunner = (changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
 export type StreamTenantOption = {
     readonly streamTenantId?: TenantId | undefined;
@@ -62,7 +65,7 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
         id: EntityId;
         version?: number | undefined;
         changes: Record<string, unknown>;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & {
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & ParentVisibilityGateOption & {
         skipOptimisticLock?: boolean;
         skipUnchanged?: boolean;
         includeDeleted?: boolean;
@@ -71,13 +74,13 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
     }) => Promise<WriteResult<SaveContext>>;
     delete: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption) => Promise<WriteResult<DeleteContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & ParentVisibilityGateOption) => Promise<WriteResult<DeleteContext>>;
     forget: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<DeleteContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & ParentVisibilityGateOption) => Promise<WriteResult<DeleteContext>>;
     restore: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<SaveContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & ParentVisibilityGateOption) => Promise<WriteResult<SaveContext>>;
     list: (payload: {
         cursor?: string | undefined;
         limit?: number | undefined;

package/dist/fields-derived.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+/** Display type a derived value formats as — drives the column's renderer
+ *  choice in the view-model, parallel to FieldDefinition["type"]. Single-column
+ *  types only: `money` is excluded because it needs a `<name>Currency`
+ *  companion column a derived field has no place to put — use `number`/
+ *  `decimal` plus a `{ format: "currency" }` column renderer instead. */
+export type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp";
+/** Clock injected into `derive` — never read `Temporal.Now`/`Date` inside a
+ *  derive body (no-date-api guard + testability). The list-query handler passes
+ *  the read-time instant; unit tests pass a fixed one. */
+export type DeriveContext = {
+    readonly asOf: Temporal.Instant;
+};
+export type DerivedFieldDef = {
+    readonly valueType: DerivedValueType;
+    /** Pure function of the stored row + clock. Returns the JSON-safe display
+     *  value (e.g. integer minor units for a currency column, ISO string for a
+     *  `date`). */
+    readonly derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown;
+};
+export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
+/** Client-facing projection of DerivedFieldDef — `derive` is server-only and
+ *  not JSON-safe (would trip the output-walk guard), so the browser schema
+ *  only ever carries `valueType`. A real `Pick`, not a same-shape cast: TS
+ *  itself proves `derive` isn't there instead of a `{ valueType } as
+ *  DerivedFieldDef` cast lying about a field that's actually missing. */
+export type ClientDerivedFieldDef = Pick<DerivedFieldDef, "valueType">;

package/dist/fields-derived.js

@@ -0,0 +1,20 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+// --- Derived (computed) fields ---
+//
+// A derived field is read-time only: its value is computed from the stored row
+// (and the clock) when an entityList query runs (676/2 — NOT detail; only the
+// "list" case in entity-handlers.ts calls augmentDerivedFields), never
+// persisted. It lives in
+// `EntityDefinition.derivedFields` — deliberately NOT in `fields`, so it
+// produces no DB column, never enters a write schema, and can't be the target
+// of an entityEdit. A declarative `entityList` can name it like any column and
+// the view-model renders the appended value.
+//
+// LIMIT: derived columns are DISPLAY ONLY. A declarative `entityList` loads its
+// rows server-side and a column-header sort round-trips to the server, where
+// `executor.list` sorts/filters/searches over real SQL columns — so a derived
+// field (no column) silently no-ops. There is no client-side sort path. Need a
+// derived value sortable/searchable? Materialize it as a stored field; it then
+// rides the existing `searchable`/`sortable` machinery. Time-dependent values
+// (as-of-today) can't be materialized without a daily re-index anyway.
+export {};

package/dist/fields.d.ts

@@ -1,8 +1,10 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import type { VariantSpec } from "./derivatives-types.ts";
+import type { DerivedFieldsMap } from "./fields-derived.ts";
 import type { EventUpcastCtx } from "./handlers.ts";
 import type { OwnershipMap } from "./ownership.ts";
 import type { EntityTenancy } from "./tenancy-brand.ts";
+export type { ClientDerivedFieldDef, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, } from "./fields-derived.ts";
 export type FieldAccess = {
     readonly read?: OwnershipMap | readonly string[];
     readonly write?: OwnershipMap | readonly string[];
@@ -78,6 +80,9 @@ export type RetentionDef = {
     readonly strategy: "hardDelete" | "softDelete" | "anonymize" | "blockDelete";
     readonly reference?: string;
 };
+/** Where rows without a value sort in a list, in both directions. Without it Postgres decides:
+ *  last ascending, first descending. */
+export type SortNulls = "first" | "last";
 export type TextFieldDef = {
     readonly type: "text";
     /** Optional free-text semantics for the AI agent manifest — never rendered;
@@ -93,6 +98,7 @@ export type TextFieldDef = {
     readonly required?: boolean;
     readonly searchable?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     /** Allows screen filters on this field.
      *  The boot validator rejects filters with `filterable !== true`.
      *  Default: false, analogous to `sortable`, and therefore opt-in. */
@@ -176,6 +182,7 @@ export type BooleanFieldDef = {
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly default?: boolean;
@@ -217,6 +224,7 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
     readonly options: TOptions;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly default?: TOptions[number];
@@ -297,6 +305,7 @@ export type NumberFieldDef = {
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly default?: number;
@@ -333,6 +342,7 @@ export type BigIntFieldDef = {
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly default?: number;
@@ -357,6 +367,7 @@ export type DecimalFieldDef = {
     readonly scale: number;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly default?: number;
@@ -385,6 +396,7 @@ export type MoneyFieldDef = {
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly access?: FieldAccess;
@@ -421,6 +433,7 @@ export type ReferenceFieldDef = {
      *  boot validator rejects it otherwise, since ordering by a UUID produces a
      *  sequence that looks meaningful to the user but is arbitrary. */
     readonly sortable?: true;
+    readonly sortNulls?: SortNulls;
     /** Fill the picker from this query handler instead of the referenced
      *  entity's own list handler — for targets whose identity is
      *  composed from joined rows, where no single column of the referenced
@@ -537,6 +550,9 @@ export type EmbeddedFieldDef = {
 export type JsonbFieldDef = {
     readonly type: "jsonb";
     readonly description?: string;
+    /** `"array"`: the field holds a JSON array, so a row that never wrote it reads `[]` and writes
+     *  take an array. Default `"object"` (`{}`, writes take a plain object). */
+    readonly emptyValue?: JsonbEmptyValue;
     readonly sensitive?: boolean;
     /** A later run reads this field's value as an instruction — prompt, rule,
      *  template. Every create/update whose payload writes it requires agent.risk
@@ -545,11 +561,13 @@ export type JsonbFieldDef = {
     readonly readAsInstruction?: boolean;
     readonly access?: FieldAccess;
 } & ResolvedPiiFlags;
+export type JsonbEmptyValue = "object" | "array";
 export type DateFieldDef = {
     readonly type: "date";
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly access?: FieldAccess;
@@ -567,6 +585,7 @@ export type TimestampFieldDef = {
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly access?: FieldAccess;
@@ -599,6 +618,7 @@ export type LocatedTimestampFieldDef = {
     readonly description?: string;
     readonly required?: boolean;
     readonly sortable?: boolean;
+    readonly sortNulls?: SortNulls;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
     readonly access?: FieldAccess;
@@ -675,32 +695,6 @@ export type FormFieldDefinition = Exclude<FieldDefinition, MoneyFieldDef> | (Mon
 });
 export type AnyFileFieldDef = FileFieldDef | ImageFieldDef | FilesFieldDef | ImagesFieldDef;
 export declare const NO_WIDGET_FIELD_TYPES: readonly FieldDefinition["type"][];
-/** Display type a derived value formats as — drives the column's renderer
- *  choice in the view-model, parallel to FieldDefinition["type"]. Single-column
- *  types only: `money` is excluded because it needs a `<name>Currency`
- *  companion column a derived field has no place to put — use `number`/
- *  `decimal` plus a `{ format: "currency" }` column renderer instead. */
-export type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp";
-/** Clock injected into `derive` — never read `Temporal.Now`/`Date` inside a
- *  derive body (no-date-api guard + testability). The list-query handler passes
- *  the read-time instant; unit tests pass a fixed one. */
-export type DeriveContext = {
-    readonly asOf: Temporal.Instant;
-};
-export type DerivedFieldDef = {
-    readonly valueType: DerivedValueType;
-    /** Pure function of the stored row + clock. Returns the JSON-safe display
-     *  value (e.g. integer minor units for a currency column, ISO string for a
-     *  `date`). */
-    readonly derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown;
-};
-export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
-/** Client-facing projection of DerivedFieldDef — `derive` is server-only and
- *  not JSON-safe (would trip the output-walk guard), so the browser schema
- *  only ever carries `valueType`. A real `Pick`, not a same-shape cast: TS
- *  itself proves `derive` isn't there instead of a `{ valueType } as
- *  DerivedFieldDef` cast lying about a field that's actually missing. */
-export type ClientDerivedFieldDef = Pick<DerivedFieldDef, "valueType">;
 export type TransitionMap = Readonly<Record<string, readonly string[]>>;
 /** Composite index on an entity. Columns are referenced by field name
  *  (camelCase). `buildEntityTable` maps them to snake_case column names and
@@ -867,4 +861,3 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
      *  privilegedRoles do not bypass it, the uploader check stays. */
     readonly attachedFileAccess?: "record-only";
 };
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.395.0",
+  "version": "0.397.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",