@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/dist/observability/provider.d.ts

@@ -0,0 +1,24 @@
+import type { Meter } from "./metric.js";
+import type { Tracer } from "./span.js";
+export type SamplingConfig = {
+    readonly tracing?: number;
+    readonly alwaysOnError?: boolean;
+    readonly alwaysOnSlow?: {
+        readonly thresholdMs: number;
+    };
+};
+export type SensitiveFilterConfig = {
+    readonly redactedHeaders: readonly string[];
+    readonly redactedQueryParams: readonly string[];
+    readonly redactedAttributeKeyPatterns: readonly RegExp[];
+};
+export type ObservabilityOptions = {
+    readonly sampling?: SamplingConfig;
+    readonly sensitiveFilter?: Partial<SensitiveFilterConfig>;
+};
+export interface ObservabilityProvider {
+    readonly name: string;
+    readonly tracer: Tracer;
+    readonly meter: Meter;
+    shutdown(): Promise<void>;
+}

package/dist/observability/provider.js

@@ -0,0 +1,4 @@
+// Observability provider contract — the "plug" that implementations (noop,
+// console, otlp, prometheus) fulfil. Configuration types that consumers
+// (buildServer, setupTestStack) hand in also live here.
+export {};

package/dist/observability/span.d.ts

@@ -0,0 +1,32 @@
+export type SpanAttributeValue = string | number | boolean;
+export type SpanAttributes = Record<string, SpanAttributeValue>;
+export type SpanStatus = "unset" | "ok" | "error";
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+export type SerializedTraceContext = {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly baggage?: Readonly<Record<string, string>>;
+};
+export type StartSpanOptions = {
+    readonly parent?: Span | SerializedTraceContext;
+    readonly attributes?: SpanAttributes;
+    readonly kind?: SpanKind;
+    readonly startTime?: number;
+};
+export interface Span {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | undefined;
+    readonly name: string;
+    setAttribute(key: string, value: SpanAttributeValue): void;
+    setAttributes(attrs: SpanAttributes): void;
+    setStatus(status: SpanStatus, message?: string): void;
+    recordException(error: Error): void;
+    end(endTime?: number): void;
+    readonly ended: boolean;
+}
+export interface Tracer {
+    startSpan(name: string, options?: StartSpanOptions): Span;
+    withSpan<T>(name: string, optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>), fn?: (span: Span) => Promise<T>): Promise<T>;
+    getActiveSpan(): Span | undefined;
+}

package/dist/observability/span.js

@@ -0,0 +1,4 @@
+// Span + Tracer contract. Provider implementations (noop, recording → console/otlp)
+// all speak this — everything else (middleware, dispatcher, db, redis, jobs)
+// is provider-agnostic.
+export {};

package/dist/ownership.d.ts

@@ -0,0 +1,33 @@
+import type { SessionUser } from "./handlers.js";
+export type SqlFragment = {
+    readonly sqlText: string;
+    readonly params: readonly unknown[];
+};
+export type OwnershipRef = string;
+export type FromRuleKind = "user" | "claim";
+export type FromRule = {
+    readonly kind: "from";
+    readonly refKind: FromRuleKind;
+    readonly refPath: string;
+    readonly column: string;
+};
+export type WhereRuleContext<TTable = unknown> = {
+    readonly table: TTable;
+    readonly tableName: string;
+    readonly paramStart: number;
+};
+export type WhereRule<TTable = unknown> = {
+    readonly kind: "where";
+    readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
+};
+export type OwnershipRule = "all" | FromRule | WhereRule;
+export type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+export type OwnershipClause = {
+    readonly kind: "pass";
+} | {
+    readonly kind: "empty";
+} | {
+    readonly kind: "sql";
+    readonly sqlText: string;
+    readonly params: readonly unknown[];
+};

package/dist/ownership.js

@@ -0,0 +1,5 @@
+// --- Ownership ---
+// Pure types for the declarative Claims → Access bridge. Runtime (from(),
+// matchesRule(), buildOwnershipClause()) stays in engine/ownership.ts, which
+// re-exports these for backwards compatibility.
+export {};

package/dist/projection.d.ts

@@ -0,0 +1,38 @@
+import type { RunIn } from "./config.js";
+import type { DbRunner } from "./db-connection.js";
+import type { StoredEvent } from "./event-store-types.js";
+import type { EntityDefinition } from "./fields.js";
+import type { MultiStreamApplyContext } from "./multi-stream-apply-context-types.js";
+import type { SchemaTable } from "./schema-table-types.js";
+export type ProjectionTable = SchemaTable;
+export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: DbRunner, table: ProjectionTable) => Promise<void>;
+export type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: DbRunner, ctx: MultiStreamApplyContext) => Promise<void>;
+export type ProjectionDefinition = {
+    readonly name: string;
+    readonly source: string | readonly string[];
+    readonly extraSources?: readonly string[];
+    readonly table: ProjectionTable;
+    readonly entity?: EntityDefinition;
+    readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
+    readonly isImplicit?: boolean;
+};
+export type EntityProjectionExtension = {
+    readonly sources?: readonly string[];
+    readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
+};
+export type MspErrorPolicy = {
+    readonly skipApplyErrors?: boolean;
+};
+export type MspErrorMode = {
+    readonly continuous?: MspErrorPolicy;
+    readonly rebuild?: MspErrorPolicy;
+};
+export type MultiStreamProjectionDefinition = {
+    readonly name: string;
+    readonly table?: ProjectionTable;
+    readonly apply: Readonly<Record<string, MultiStreamApplyFn>>;
+    readonly errorMode?: MspErrorMode;
+    readonly runIn?: RunIn;
+    readonly delivery?: "shared" | "per-instance";
+    readonly startFrom?: "beginning" | "now";
+};

package/dist/projection.js

@@ -0,0 +1 @@
+export {};

package/dist/rate-limit-types.d.ts

@@ -0,0 +1,19 @@
+import type { Temporal } from "temporal-polyfill";
+export type RateLimitDecision = {
+    readonly allowed: boolean;
+    readonly limit: number;
+    readonly remaining: number;
+    readonly retryAfterSeconds: number;
+    readonly windowSeconds: number;
+    readonly resetAt: Temporal.Instant;
+};
+export type RateLimitConfig = {
+    readonly limit: number;
+    readonly windowSeconds: number;
+    readonly cost?: number;
+};
+export type RateLimitResolver = {
+    check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+    enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+    peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
+};

package/dist/rate-limit-types.js

@@ -0,0 +1 @@
+export {};

package/dist/relations.d.ts

@@ -0,0 +1,25 @@
+export type OnDeleteStrategy = "cascade" | "restrict" | "setNull" | "nothing";
+export type BelongsToRelation = {
+    readonly type: "belongsTo";
+    readonly target: string;
+    readonly foreignKey: string;
+};
+export type HasManyRelation = {
+    readonly type: "hasMany";
+    readonly target: string;
+    readonly foreignKey: string;
+    readonly onDelete?: OnDeleteStrategy;
+    readonly nestedWrite?: boolean;
+};
+export type ManyToManyRelation = {
+    readonly type: "manyToMany";
+    readonly target: string;
+    readonly through: {
+        readonly table: string;
+        readonly sourceKey: string;
+        readonly targetKey: string;
+    };
+    readonly onDelete?: OnDeleteStrategy;
+};
+export type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
+export type EntityRelations = Readonly<Record<string, RelationDefinition>>;

package/dist/relations.js

@@ -0,0 +1 @@
+export {};

package/dist/schema-table-types.d.ts

@@ -0,0 +1,15 @@
+import type { EntityTableMeta, PgType } from "./entity-table-meta-types.js";
+export declare const KUMIKO_NAME_SYMBOL: unique symbol;
+export declare const KUMIKO_COLUMNS_SYMBOL: unique symbol;
+export declare const KUMIKO_META_SYMBOL: unique symbol;
+export type ColumnHandle = {
+    readonly name: string;
+    readonly pgType: PgType;
+    readonly getSQLType: () => string;
+};
+export type SchemaTable = EntityTableMeta & {
+    readonly [KUMIKO_NAME_SYMBOL]: string;
+    readonly [KUMIKO_COLUMNS_SYMBOL]: Record<string, ColumnHandle>;
+    readonly [KUMIKO_META_SYMBOL]: EntityTableMeta;
+    readonly [field: string]: unknown;
+};

package/{src/schema-table-types.ts → dist/schema-table-types.js}

@@ -1,5 +1,3 @@
-import type { EntityTableMeta, PgType } from "./entity-table-meta-types";
-
 // Global-registry symbols the native dialect stamps onto every SchemaTable —
 // shared identity so downstream introspection (Symbol.for lookups) matches
 // exactly the same unique-symbol type as the one used to construct the table.
@@ -10,21 +8,3 @@ export const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
 // field named `source`/`columns`/`tableName`/… could shadow; readers that
 // need the canonical meta regardless of shadowing use this symbol instead.
 export const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
-
-// Column handle exposed on the SchemaTable. The `name` is the SQL column
-// name (snake_case); legacy code accesses `table.fieldName.name` to
-// produce raw SQL.
-export type ColumnHandle = {
-  readonly name: string;
-  readonly pgType: PgType;
-  readonly getSQLType: () => string;
-};
-
-// SchemaTable — opaque shape with both EntityTableMeta + Symbol-based
-// introspection. Returned by `table(...)`.
-export type SchemaTable = EntityTableMeta & {
-  readonly [KUMIKO_NAME_SYMBOL]: string;
-  readonly [KUMIKO_COLUMNS_SYMBOL]: Record<string, ColumnHandle>;
-  readonly [KUMIKO_META_SYMBOL]: EntityTableMeta;
-  readonly [field: string]: unknown;
-};