js-bao 0.5.0 → 0.5.2

package/dist/cloudflare-do.d.cts

@@ -31,8 +31,32 @@ interface FieldOptions {
     unique?: boolean;
     default?: any | (() => any);
     autoAssign?: boolean;
+    /**
+     * Auto-timestamp this field with `Date.now()` (milliseconds) on save.
+     *
+     * - `'create'` — stamp only on the first save (when `isNew === true`).
+     * - `'update'` — stamp on every save (create AND update).
+     * - `'both'`   — stamp on every save (create AND update).
+     *
+     * If the caller passes an explicit value for the field in `data`, the
+     * explicit value wins and the stamp is skipped. The stamp is applied
+     * in `beforeSave` BEFORE any user-defined hooks, so user hooks may
+     * still overwrite the value if they wish (last writer wins).
+     */
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
+    /**
+     * Allowed-value set for a `string` field. When present, the codegen
+     * generators (database-type codegen + doc-model v2 codegen) emit a
+     * TypeScript string-literal union (`"a" | "b" | "c"`) instead of a bare
+     * `string` for this field.
+     *
+     * Advisory / codegen-only: this is a TS-emission hint. The runtime and the
+     * server do NOT enforce enum membership on write (see #843). Only valid on
+     * `string` fields, and must be a non-empty array of strings.
+     */
+    enum?: string[];
 }
 interface UniqueConstraintConfig {
     name: string;
@@ -957,6 +981,18 @@ interface HookResult {
     allow: boolean;
     /** Reason for denial (returned to client as error message) */
     reason?: string;
+    /**
+     * Names of fields the hook wrote onto `ctx.data` that the DO should echo
+     * back to the caller in the write response's `appliedFields`. A `beforeSave`
+     * hook can compute and set fields on `ctx.data` (e.g. app-level triggers that
+     * derive a value from the submitted row); those values are persisted but are
+     * invisible to a caller that rebuilds a change event from its original
+     * submission inputs. Reporting the names here lets the DO read the final
+     * post-hook values back and thread them into `appliedFields` so the caller
+     * can propagate them (#1476). The hook contract stays generic — it names the
+     * fields it applied and does not need to know how the caller uses them.
+     */
+    serverAppliedFieldNames?: string[];
 }
 /** Result from beforeQuery hooks — can inject additional filters */
 interface BeforeQueryResult extends HookResult {
@@ -1023,6 +1059,25 @@ interface SaveRequest {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-call auto-timestamp directives for schemaless writes.
+     *
+     * Each entry is a list of field names to stamp with `Date.now()`
+     * (milliseconds) at the corresponding lifecycle event:
+     *
+     * - `create` — field is stamped only when the record is new
+     *   (no row exists yet for this `modelName` + `id`).
+     * - `update` — field is stamped on every save (create AND update).
+     *
+     * If the caller already provided an explicit value for the field
+     * in `data`, the explicit value wins and the stamp is skipped.
+     * Stamping happens BEFORE the `beforeSave` user hook runs, so user
+     * hooks may still overwrite the stamped value if they wish.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface DeleteRequest {
     modelName: string;
@@ -1064,6 +1119,20 @@ interface QueryResponse {
 interface SaveResponse {
     success: boolean;
     id: string;
+    /**
+     * Server-applied field values the DO wrote AFTER the caller's submission
+     * inputs were assembled, read back from the final post-hook `data`
+     * (#1476, consolidating the #1462 `stamps` channel). This is the single
+     * "server-applied fields" channel: it carries both the applied `autoStamps`
+     * timestamps and any fields a `beforeSave` hook reported via
+     * `serverAppliedFieldNames` (e.g. app-level trigger-computed values). Present
+     * only when at least one such field ended up with a value. Lets the Worker
+     * thread these values into the change-event `data` it broadcasts to
+     * subscribers — otherwise a `select`-listed stamped or trigger-computed field
+     * never reaches the frame, because the frame is rebuilt from the submission
+     * inputs (which predate the DO-side write).
+     */
+    appliedFields?: Record<string, any>;
 }
 interface DeleteResponse {
     success: boolean;
@@ -1131,10 +1200,23 @@ interface PatchRequest {
     data: Record<string, any>;
     stringSets?: Record<string, string[]>;
     condition?: DocumentFilter;
+    /**
+     * Per-call auto-timestamp directives. A patch is always treated as
+     * an update (`isNew === false`), so only the `update` list is
+     * applied; the `create` list is ignored on patch.
+     *
+     * Explicit values in `data` win.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface PatchResponse {
     success: boolean;
     id: string;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchOperation {
     op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
@@ -1146,15 +1228,62 @@ interface BatchOperation {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-operation auto-timestamp directives. Same semantics as
+     * `SaveRequest.autoStamps` / `PatchRequest.autoStamps`. Applied
+     * BEFORE the user `beforeSave` hook runs, with explicit values
+     * in `data` always winning.
+     *
+     * For `op: "patch"`, only the `update` list applies (patches are
+     * always treated as updates).
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface BatchRequest {
     operations: BatchOperation[];
+    /**
+     * All-or-nothing execution (#1478). When `true`, the FIRST operation that
+     * fails inside the transaction — hook denial, condition / `ifNotExists` /
+     * unique violation, record-not-found, or upsert validation error — aborts
+     * the whole batch: every write is rolled back and the handler returns an
+     * error naming the failed step with its natural HTTP status (see
+     * `BatchOperationResult.status`). When `false` or absent (the default), each
+     * operation's outcome is recorded independently and successful siblings
+     * commit — the partial-success behavior import-bulk and applyToQuery rely on.
+     */
+    atomic?: boolean;
 }
+/**
+ * Stable, machine-readable failure tag on a failed `BatchOperationResult`
+ * (#1478). Derived at each failure site — never inferred from the `error`
+ * string. `#1389` (conditional writes + fencing-token enforcement) surfaces its
+ * condition / stale-token rejections through this same channel.
+ */
+type BatchFailureCode = "NOT_FOUND" | "HOOK_DENIED" | "CONDITION_NOT_MET" | "ALREADY_EXISTS" | "UNIQUE_VIOLATION" | "VALIDATION_ERROR";
 interface BatchOperationResult {
     success: boolean;
     id: string;
     error?: string;
+    /**
+     * Structured failure metadata (#1478), present only on a failed result. Both
+     * are derived at the failure site, not parsed back out of `error`:
+     *  - `status` — the natural HTTP status for the cause (404 not found,
+     *    403 hook denial, 409 condition / `ifNotExists` / unique conflict,
+     *    400 upsert validation).
+     *  - `code` — a stable machine-readable tag (see `BatchFailureCode`).
+     *
+     * In atomic mode the handler reads the first failure's `status`/`code` to
+     * build the error response, so an increment-on-missing op keeps its 404 and a
+     * hook denial keeps its 403 instead of collapsing to a uniform 409.
+     */
+    status?: number;
+    code?: BatchFailureCode;
     values?: Record<string, number>;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchResponse {
     results: BatchOperationResult[];
@@ -1186,6 +1315,7 @@ interface SchemaFieldInfo {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1207,6 +1337,35 @@ interface SchemaModelInfo {
 interface SchemaResponse {
     models: Record<string, SchemaModelInfo>;
 }
+/**
+ * Return an error message if `fieldName` is a reserved field name
+ * (matches the policy enforced by `_checkReservedFields` on incoming
+ * record data). Returns `null` if the name is acceptable.
+ *
+ * "id" is allowed (stripped before storage in the JSON column).
+ * "type" maps to the internal `_type` column. Any name starting with
+ * "_" is internal.
+ *
+ * @internal
+ */
+declare function checkReservedFieldName(fieldName: string): string | null;
+/**
+ * Validate that none of the field names listed in `autoStamps.create` /
+ * `autoStamps.update` are reserved. Returns an error message on the
+ * first violation, or `null` if everything is acceptable.
+ *
+ * Codex P2 #2: `_checkReservedFields` only inspects the keys already
+ * present in `data`. Without this check, a request such as
+ * `{ autoStamps: { update: ["type"] } }` would pass the data-level
+ * guard and then have `applyAutoStamps` add a reserved key after the
+ * fact, bypassing the protection.
+ *
+ * @internal
+ */
+declare function checkAutoStampsReservedFields(autoStamps: {
+    create?: string[];
+    update?: string[];
+} | undefined): string | null;
 /**
  * Create a Durable Object class for schemaless database storage.
  *
@@ -1356,6 +1515,33 @@ declare function createDatabaseDO(config?: DatabaseDOConfig): {
  */
 declare const createDocumentDO: typeof createDatabaseDO;
 
+/**
+ * Decoding for rows read out of the schemaless `records` table.
+ *
+ * A `SELECT` built by `JsonQueryTranslator` comes back in one of two shapes:
+ * the whole record (`_id`, `_type`, `_data`), or — under an inclusion
+ * projection — one column per projected field. Both shapes are turned back
+ * into a record object here, so every reader of the store (the DatabaseDO's
+ * query/get paths, the per-document SQLite projection) hands callers the same
+ * values for the same stored record.
+ */
+/**
+ * Column-alias prefix for a projected field whose value is selected as JSON
+ * text. The prefix marks the column as still-encoded so
+ * {@link parseRecordRow} knows to decode it; field names cannot start with
+ * `_` (the write path rejects them as reserved), so the prefix can never
+ * collide with a real field.
+ */
+declare const PROJECTED_JSON_ALIAS_PREFIX = "_json_";
+/** Column alias under which a projected field's JSON text is selected. */
+declare function projectedJsonAlias(fieldName: string): string;
+/**
+ * Decode one row of a `records` SELECT into a record object: `_id`/`_type`
+ * become `id`/`type`, `_data` is parsed when present, and any projected
+ * column is decoded back to its stored value.
+ */
+declare function parseRecordRow(row: Record<string, any>): Record<string, any>;
+
 /**
  * Cloudflare Worker Router Template
  *
@@ -1432,6 +1618,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1676,6 +1863,17 @@ declare class BaseModel implements StringSetChangeTracker {
     private ensureLocalChanges;
     private hasLocalChange;
     private getFromYjs;
+    /**
+     * Defensive normalization for the read/sync boundary (issue #625).
+     *
+     * Stringset fields are owned by getStringSetFromYjs (which expects the
+     * raw Y.Map / legacy plain-object shape — #561 / #601), so they pass
+     * through untouched. For any other field, a composite Yjs primitive
+     * (Y.Map / Y.Array / Y.Text) must never reach user code or the DB layer
+     * raw: normalize it to its plain-JS projection (toJSON / toString) and
+     * warn, rather than throwing. Scalars pass through unchanged.
+     */
+    private normalizeNonStringSetValue;
     private getValue;
     private setValue;
     get isDirty(): boolean;
@@ -1810,6 +2008,27 @@ declare class BaseModel implements StringSetChangeTracker {
      */
     static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
     static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    /**
+     * Resolve a record by its unique-constraint field values via an engine query.
+     * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+     * entry for a key.
+     *
+     * The index map is a cache over the SQLite projection, not the source of
+     * truth: every record is loaded into the projection on `initializeForDocument`
+     * regardless of index presence, but a record written by a client predating
+     * index maintenance (legacy data) is missing from the index. Such a record
+     * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+     * check. A query over the constraint fields finds it reliably.
+     *
+     * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+     * the document that holds it, via `queryOne`) or `null`. Callers decide
+     * whether to heal the missing index entry (write paths) and do their own
+     * logging — this method never mutates the index, so read paths stay
+     * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+     * constraint field means the record does not participate in the constraint,
+     * so no query runs.
+     */
+    private static _resolveByUniqueFallback;
     static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
     static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
         id?: string;
@@ -1910,6 +2129,11 @@ declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSche
 
 /**
  * Infer a _meta_ type string from a JS runtime value.
+ *
+ * Only an all-`true` Y.Map (the stringset wire shape) is tagged as
+ * `stringset` (issue #625) — a Y.Map carrying a composite payload, or a
+ * Y.Array / Y.Text, is not a stringset and stays untyped (`null`) rather
+ * than being mis-tagged.
  */
 declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
 /**
@@ -1941,4 +2165,16 @@ declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSche
  */
 declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation$1 as AggregationOperation, type AggregationOptions$1 as AggregationOptions, type AggregationResult$1 as AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type Env, type ErrorResponse, type GroupByField$1 as GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SchemaConstraintInfo, type SchemaFieldInfo, type SchemaModelInfo, type SchemaResponse, type SqlStorage, type SqlStorageCursor, type StringSetMembership$1 as StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, clearMetaSyncCache, createDatabaseDO, createDocumentDO, discoverModelNames, discoverSchema, handleRequest, inferFieldType, loadSchemaFromTomlString, registerFunctionDefault, schemaToToml, syncInferredMeta, syncModelMeta };
+/**
+ * Produce a deterministic, SQL-safe alias suffix derived from arbitrary input.
+ * The resulting string always matches our identifier policy when prefixed with
+ * a valid identifier segment.
+ */
+declare function deterministicIdentifierHash(value: string): string;
+/**
+ * Build a safe alias using a prefix that already conforms to the identifier
+ * policy along with a deterministic hash of the raw descriptor.
+ */
+declare function buildSafeAlias(prefix: string, rawDescriptor: string): string;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation$1 as AggregationOperation, type AggregationOptions$1 as AggregationOptions, type AggregationResult$1 as AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type CountRequest, type CountResponse, type DatabaseDOConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DocumentDOConfig, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, DurableObjectEngine, type DurableObjectEngineOptions, type DurableObjectId, type DurableObjectNamespace, type DurableObjectState, type DurableObjectStorage, type DurableObjectStub, type Env, type ErrorResponse, type GroupByField$1 as GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, JsonQueryTranslator, type JsonQueryTranslatorOptions, JsonSchemaDDL, type JsonSchemaOptions, PROJECTED_JSON_ALIAS_PREFIX, type PatchRequest, type PatchResponse, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveRequest, type SaveResponse, type SchemaConstraintInfo, type SchemaFieldInfo, type SchemaModelInfo, type SchemaResponse, type SqlStorage, type SqlStorageCursor, type StringSetMembership$1 as StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, buildSafeAlias, checkAutoStampsReservedFields, checkReservedFieldName, clearMetaSyncCache, createDatabaseDO, createDocumentDO, deterministicIdentifierHash, discoverModelNames, discoverSchema, handleRequest, inferFieldType, loadSchemaFromTomlString, parseRecordRow, projectedJsonAlias, registerFunctionDefault, schemaToToml, syncInferredMeta, syncModelMeta };