effect-dynamodb 0.1.0 → 1.1.0

package/dist/Entity.js

@@ -100,7 +100,7 @@ const makeImpl = (config) => {
     const isSchemaClass = typeof rawModel === "function";
     const modelFields = getFields(rawModel);
     const hasHiddenFields = Object.values(modelFields).some(isHidden);
-    const systemFields = resolveSystemFields(config.timestamps, config.versioned);
+    const systemFields = resolveSystemFields(config.timestamps, config.versioned, config.timeSeries);
     // ---------------------------------------------------------------------------
     // Validate indexes
     // ---------------------------------------------------------------------------
@@ -123,6 +123,82 @@ const makeImpl = (config) => {
             }
         }
     }
+    // ---------------------------------------------------------------------------
+    // Validate timeSeries config (EDD-9010..9016)
+    // ---------------------------------------------------------------------------
+    if (config.timeSeries !== undefined && config.timeSeries !== null) {
+        const ts = config.timeSeries;
+        const orderBy = ts.orderBy;
+        // EDD-9010: orderBy must name a model field
+        if (!(orderBy in modelFields)) {
+            throw new Error(`[EDD-9010] Entity "${config.entityType}": timeSeries.orderBy "${orderBy}" does not name a model field. ` +
+                `Valid model fields: ${Object.keys(modelFields).sort().join(", ")}`);
+        }
+        // EDD-9011: orderBy must not be a primary-key composite (PK or SK)
+        const primary = config.indexes.primary;
+        const pkSkComposites = new Set([...primary.pk.composite, ...primary.sk.composite]);
+        if (pkSkComposites.has(orderBy)) {
+            throw new Error(`[EDD-9011] Entity "${config.entityType}": timeSeries.orderBy "${orderBy}" must not appear ` +
+                `in the primary key pk or sk composite — it shadows the #e# event-SK infix.`);
+        }
+        // EDD-9012: mutually exclusive with versioned
+        if (config.versioned !== undefined && config.versioned !== null && config.versioned !== false) {
+            throw new Error(`[EDD-9012] Entity "${config.entityType}": timeSeries and versioned are mutually exclusive. ` +
+                `Pick one consistency model per entity.`);
+        }
+        // EDD-9015: mutually exclusive with softDelete
+        if (config.softDelete !== undefined &&
+            config.softDelete !== null &&
+            config.softDelete !== false) {
+            throw new Error(`[EDD-9015] Entity "${config.entityType}": timeSeries and softDelete are mutually exclusive. ` +
+                `Append on a soft-deleted item would land on a new empty row — not a sound resurrection model.`);
+        }
+        // EDD-9016: appendInput is required
+        if (ts.appendInput === undefined || ts.appendInput === null) {
+            throw new Error(`[EDD-9016] Entity "${config.entityType}": timeSeries.appendInput is required. ` +
+                `Define a Schema.Struct whose fields are the subset of the model allowed in .append() input. ` +
+                `Fields outside appendInput are preserved on the current item — this is the enrichment-preservation guarantee. ` +
+                `To opt out (dangerous), pass the full model schema explicitly.`);
+        }
+        const appendInputFields = (() => {
+            const ai = ts.appendInput;
+            if ("fields" in ai && typeof ai.fields === "object") {
+                return Object.keys(ai.fields);
+            }
+            throw new Error(`[EDD-9016] Entity "${config.entityType}": timeSeries.appendInput must be a Schema.Struct or Schema.Class (.fields required).`);
+        })();
+        const appendInputFieldSet = new Set(appendInputFields);
+        // EDD-9013: appendInput must include orderBy + all PK/SK composites
+        if (!appendInputFieldSet.has(orderBy)) {
+            throw new Error(`[EDD-9013] Entity "${config.entityType}": timeSeries.appendInput must include orderBy "${orderBy}". ` +
+                `Without it .append() cannot evaluate the CAS condition.`);
+        }
+        for (const composite of pkSkComposites) {
+            if (!appendInputFieldSet.has(composite)) {
+                throw new Error(`[EDD-9013] Entity "${config.entityType}": timeSeries.appendInput missing primary-key composite "${composite}". ` +
+                    `Every PK/SK composite must appear in appendInput so the event can be addressed.`);
+            }
+        }
+        // EDD-9014: orderBy must not name a ref field or ref-derived ${name}Id field
+        for (const fieldName of Object.keys(modelFields)) {
+            if (isRefField(fieldName, config.model)) {
+                if (orderBy === fieldName || orderBy === `${fieldName}Id`) {
+                    throw new Error(`[EDD-9014] Entity "${config.entityType}": timeSeries.orderBy "${orderBy}" names a ref ` +
+                        `or ref-derived id field. Refs are create-time denormalisations and cannot serve as the event clock.`);
+                }
+            }
+        }
+        // Also: appendInput must not declare any ref-derived ${name}Id field —
+        // ref changes go through .update(), not .append() (§4.6).
+        for (const fieldName of Object.keys(modelFields)) {
+            if (isRefField(fieldName, config.model)) {
+                if (appendInputFieldSet.has(`${fieldName}Id`)) {
+                    throw new Error(`[EDD-9014] Entity "${config.entityType}": timeSeries.appendInput must not include ref-derived ` +
+                        `"${fieldName}Id" — refs cannot be reassigned via .append(). Use .update() to change a ref.`);
+                }
+            }
+        }
+    }
     const resolvedRefs = config.refs
         ? Object.entries(config.refs).map(([fieldName, refValue]) => {
             // Extract entity from shorthand or expanded form
@@ -182,7 +258,7 @@ const makeImpl = (config) => {
     }
     // Resolve identifier field name from model annotation
     const resolvedIdentifier = getIdentifierField(config.model)?.name;
-    const schemas = buildDerivedSchemas(modelFields, allIndexes, systemFields, resolvedRefs, immutableFields, resolvedIdentifier);
+    const schemas = buildDerivedSchemas(modelFields, allIndexes, systemFields, resolvedRefs, immutableFields, resolvedIdentifier, config.timeSeries);
     // schema and tableTag are injected via _configure() when the entity is registered
     // on a Table and bound through DynamoClient.make(). They are captured by operation
     // closures and resolved at runtime (inside Effects), not at definition time.
@@ -1727,6 +1803,261 @@ const makeImpl = (config) => {
         return yield* decodeAs(raw, result.Attributes, mode);
     }), self, input);
     // ---------------------------------------------------------------------------
+    // append operation — time-series primitive (only when `timeSeries` configured)
+    //
+    // Two-item `TransactWriteItems`:
+    //  - UpdateItem on current: scoped SET (appendInput fields only) + CAS on
+    //    `orderBy`, with GSI keys recomposed when any appendInput field is a
+    //    GSI composite. `createdAt` uses if_not_exists on first append.
+    //  - Put of event: full decoded input + __edd_e__ + _ttl (if configured),
+    //    GSI keys stripped, SK replaced with `<currentSk>#e#<orderByValue>`.
+    //
+    // On TransactionCancelled or ConditionalCheckFailed, we issue a follow-up
+    // GetItem on the primary key and return `{ applied: false, reason: "stale",
+    // current }`. On success, same follow-up GetItem yields the post-append
+    // current. See `docs/designs/timeseries.md` §4.
+    // ---------------------------------------------------------------------------
+    const timeSeriesConfig = config.timeSeries;
+    const append = (input, userCondition) => Effect.gen(function* () {
+        if (!timeSeriesConfig) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "append",
+                cause: "Entity is not configured with timeSeries. .append() requires timeSeries config.",
+            });
+        }
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* tableTag;
+        const orderByField = timeSeriesConfig.orderBy;
+        const ttlDuration = timeSeriesConfig.ttl;
+        const appendInputSchema = schemas.appendInputSchema;
+        // Decode input via appendInputSchema
+        const decodedInput = yield* Schema.decodeUnknownEffect(appendInputSchema)(input).pipe(Effect.mapError((cause) => new ValidationError({
+            entityType,
+            operation: "append.decode",
+            cause,
+        })));
+        const decoded = decodedInput;
+        // Compose current-item primary key (pk + sk derived from PK/SK composites in decoded)
+        const primary = config.indexes.primary;
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, decoded);
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decoded);
+        const marshalledKey = toAttributeMap({
+            [primary.pk.field]: pkValue,
+            [primary.sk.field]: currentSk,
+        });
+        // Prepare domain-serialised values for the item build.
+        // Build a shallow copy and apply date serialization (per fieldEncodings)
+        // before marshalling. This mirrors the put path.
+        const serialisedInput = { ...decoded };
+        serializeDateFields(serialisedInput);
+        // ---------- Build UpdateItem (scoped SET + CAS) ----------
+        const setClauses = [];
+        const names = {};
+        const values = {};
+        let counter = 0;
+        // Only fields named in appendInput (the serialisedInput object). This is
+        // the enrichment-preservation contract — fields outside appendInput are
+        // never touched. PK composites ARE included: they're stored as regular
+        // attributes on the item (mirrors `.put()`), and though their values
+        // never change, writing them on every append makes the first append
+        // (where the row doesn't yet exist) materialise the row correctly.
+        const pkCompositeSet = new Set(primaryKeyComposites(config.indexes));
+        for (const [attr, val] of Object.entries(serialisedInput)) {
+            if (val === undefined)
+                continue;
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = resolveDbName(attr);
+            values[valKey] = toAttributeValue(val);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        // GSI key recomposition: any GSI whose composites are touched by input.
+        // Reuses the same machinery as `.update()`. PK composites are excluded
+        // from the update payload: they're already in the key and never change
+        // during an append. Non-PK composites that overlap between appendInput
+        // and a GSI trigger recomposition, which requires the full GSI composite
+        // set (partial presence raises `PartialGsiCompositeError`).
+        const nonPkAppendFields = {};
+        for (const [attr, val] of Object.entries(decoded)) {
+            if (!pkCompositeSet.has(attr)) {
+                nonPkAppendFields[attr] = val;
+            }
+        }
+        let gsiKeys;
+        try {
+            gsiKeys = KeyComposer.composeGsiKeysForUpdate(schema, entityType, entityVersion, allIndexes, nonPkAppendFields, decoded);
+        }
+        catch (e) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "append.gsiComposites",
+                cause: e instanceof Error ? e.message : e,
+            });
+        }
+        for (const [field, value] of Object.entries(gsiKeys)) {
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = field;
+            values[valKey] = toAttributeValue(value);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        // Entity type discriminator — idempotent; ensures existing items
+        // without __edd_e__ still get tagged on first append.
+        {
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = "__edd_e__";
+            values[valKey] = toAttributeValue(entityType);
+            setClauses.push(`${nameKey} = ${valKey}`);
+            counter++;
+        }
+        // createdAt (if configured) — if_not_exists so subsequent appends leave it alone
+        if (systemFields.createdAt) {
+            const nameKey = `#a${counter}`;
+            const valKey = `:a${counter}`;
+            names[nameKey] = systemFields.createdAt;
+            values[valKey] = toAttributeValue(generateTimestamp(systemFields.createdAtEncoding));
+            setClauses.push(`${nameKey} = if_not_exists(${nameKey}, ${valKey})`);
+            counter++;
+        }
+        // CAS condition: attribute_not_exists(#pk) OR #ob < :newOb
+        names["#_tspk"] = primary.pk.field;
+        names["#_tsob"] = resolveDbName(orderByField);
+        // The comparison uses the stored domain-value representation — for
+        // DateTime.Utc this is ISO (lexicographic == chronological), for numbers
+        // it's numeric, for strings it's lexicographic. Matches how the current
+        // item stores `orderByField`.
+        const newObValue = serialisedInput[orderByField];
+        values[":_tsNewOb"] = toAttributeValue(newObValue);
+        const casCondition = "attribute_not_exists(#_tspk) OR #_tsob < :_tsNewOb";
+        let finalCondition = casCondition;
+        if (userCondition !== undefined) {
+            const uc = compileCondition(userCondition, resolveDbName);
+            finalCondition = `(${casCondition}) AND (${uc.expression})`;
+            Object.assign(names, uc.names);
+            Object.assign(values, uc.values);
+        }
+        const updateExpression = `SET ${setClauses.join(", ")}`;
+        // ---------- Build Put of event item ----------
+        const eventSk = KeyComposer.composeEventSk(currentSk, newObValue, schema.casing);
+        const eventItem = { ...decoded };
+        // Serialise date fields to storage format for the Put
+        serializeDateFields(eventItem);
+        // Rename domain → DB names for the Put (matches put path)
+        renameToDynamo(eventItem);
+        // pk + sk (event)
+        eventItem[primary.pk.field] = pkValue;
+        eventItem[primary.sk.field] = eventSk;
+        // __edd_e__
+        eventItem.__edd_e__ = entityType;
+        // _ttl
+        if (ttlDuration) {
+            eventItem._ttl = Math.floor(Date.now() / 1000) + Duration.toSeconds(ttlDuration);
+        }
+        // Events never participate in indexes: strip any GSI key fields that the
+        // naive spread above may have carried over. gsiKeys weren't written into
+        // eventItem (only decoded fields are), but defensively clear them.
+        for (const field of gsiKeyFields()) {
+            delete eventItem[field];
+        }
+        const marshalledEventItem = toAttributeMap(eventItem);
+        // ---------- Execute TransactWriteItems ----------
+        const transactResult = yield* client
+            .transactWriteItems({
+            TransactItems: [
+                {
+                    Update: {
+                        TableName: tableName,
+                        Key: marshalledKey,
+                        UpdateExpression: updateExpression,
+                        ConditionExpression: finalCondition,
+                        ExpressionAttributeNames: names,
+                        ExpressionAttributeValues: values,
+                    },
+                },
+                {
+                    Put: {
+                        TableName: tableName,
+                        Item: marshalledEventItem,
+                    },
+                },
+            ],
+        })
+            .pipe(Effect.matchEffect({
+            onSuccess: () => Effect.succeed({ stale: false }),
+            onFailure: (err) => {
+                // TransactionCancelled or ConditionalCheckFailed at the transaction
+                // level both map to "stale" (can't distinguish CAS from user-cond
+                // in v1 — see §12 decision 5).
+                if (isAwsTransactionCancelled(err.cause) || isAwsConditionalCheckFailed(err.cause)) {
+                    return Effect.succeed({ stale: true });
+                }
+                return Effect.fail(err);
+            },
+        }));
+        // Follow-up GetItem to read the current (post-append on success, winning
+        // state on stale). One read is required either way — the contract
+        // returns `Model` which demands the full row including enrichment.
+        const followUp = yield* client.getItem({
+            TableName: tableName,
+            Key: marshalledKey,
+        });
+        if (!followUp.Item) {
+            // TTL race or out-of-band delete — surface as a DynamoClientError
+            // (the previous state vanished under us). This is NOT a stale result.
+            return yield* Effect.fail(new ValidationError({
+                entityType,
+                operation: "append.followUp",
+                cause: "Current item not found after append — possible TTL race or concurrent delete.",
+            }));
+        }
+        const rawCurrent = fromAttributeMap(followUp.Item);
+        const currentModel = yield* decodeAs(rawCurrent, followUp.Item, "model");
+        if (transactResult.stale) {
+            return {
+                applied: false,
+                reason: "stale",
+                current: currentModel,
+            };
+        }
+        return { applied: true, current: currentModel };
+    });
+    // ---------------------------------------------------------------------------
+    // history operation — BoundQuery for event items only
+    // ---------------------------------------------------------------------------
+    const history = (key) => {
+        if (!timeSeriesConfig) {
+            throw new Error(`[EDD-9010] Entity "${entityType}": .history() requires timeSeries config on the entity.`);
+        }
+        const decodedKey = Schema.decodeUnknownSync(schemas.keySchema)(key);
+        const primary = config.indexes.primary;
+        const pkValue = KeyComposer.composePk(schema, entityType, primary, decodedKey);
+        const currentSk = KeyComposer.composeSk(schema, entityType, entityVersion, primary, decodedKey);
+        const prefix = KeyComposer.composeEventSkPrefix(currentSk, schema.casing);
+        const decodeHistory = (raw) => {
+            renameFromDynamo(raw);
+            deserializeDateFields(raw);
+            return Schema.decodeUnknownEffect(schemas.historyRecordSchema)(raw).pipe(Effect.map(attachPrototype), Effect.mapError((cause) => new ValidationError({
+                entityType,
+                operation: "history.decode",
+                cause,
+            })));
+        };
+        return Query.make({
+            tableName: "",
+            indexName: undefined,
+            pkField: primary.pk.field,
+            pkValue,
+            skField: primary.sk.field,
+            entityTypes: [entityType],
+            decoder: (raw) => decodeHistory(raw),
+            resolveTableName: tableTag.useSync((tc) => tc.name),
+        }).pipe(Query.where({ beginsWith: prefix }));
+    };
+    // ---------------------------------------------------------------------------
     // query namespace
     // ---------------------------------------------------------------------------
     const queryNamespace = {};
@@ -2170,6 +2501,7 @@ const makeImpl = (config) => {
         softDelete: config.softDelete,
         unique: config.unique,
         identifier: resolvedIdentifier,
+        timeSeries: config.timeSeries,
         _resolvedRefs: resolvedRefs,
         /** @internal Full decode pipeline: rename + date deser + schema decode. Used by Batch/Aggregate. */
         _decodeRecord: decodeRecord,
@@ -2206,6 +2538,8 @@ const makeImpl = (config) => {
         restore,
         purge,
         deleted: { get: deletedGet, list: deletedList },
+        append,
+        history,
         set,
         expectedVersion,
         query: queryNamespace,
@@ -2297,6 +2631,53 @@ export const bind = (entity) => Effect.gen(function* () {
             get: (key) => provide(entity.deleted.get(key)._run("record")),
             list: (key) => wrapAsBoundQuery(entity.deleted.list(key)),
         },
+        // Time-series (no-ops when entity is not configured; runtime check in
+        // the entity-level `append` returns a ValidationError).
+        append: (input, condition) => provide(entity.append(input, condition)),
+        history: (key) => {
+            const q = entity.history(key);
+            const pathBuilder = createPathBuilder();
+            const conditionOps = createConditionOps();
+            const ts = entity.timeSeries;
+            const orderBy = ts?.orderBy;
+            const entityInternals = entity;
+            const schemaRef = entityInternals._schema;
+            const entityTypeRef = entityInternals.entityType;
+            // composeSkCondition: rewrite user's .where() values by prefixing
+            // with `<currentSk>#e#` and applying serialisation + casing to the
+            // user-supplied orderBy value.
+            const primary = entity.indexes.primary;
+            const composeSkCondition = (cond) => {
+                // We need the `currentSk` + prefix. The user's `key` lets us derive
+                // `currentSk` via the same primary SK composer used by `history()`.
+                const currentSk = KeyComposer.composeSk(schemaRef, entityTypeRef, 1, primary, key);
+                const prefix = KeyComposer.composeEventSkPrefix(currentSk, schemaRef.casing);
+                const rewrite = (v) => `${prefix}${DynamoSchema.applyCasing(KeyComposer.serializeValue(v), schemaRef.casing)}`;
+                if ("eq" in cond)
+                    return { eq: rewrite(cond.eq) };
+                if ("lt" in cond)
+                    return { lt: rewrite(cond.lt) };
+                if ("lte" in cond)
+                    return { lte: rewrite(cond.lte) };
+                if ("gt" in cond)
+                    return { gt: rewrite(cond.gt) };
+                if ("gte" in cond)
+                    return { gte: rewrite(cond.gte) };
+                if ("between" in cond)
+                    return { between: [rewrite(cond.between[0]), rewrite(cond.between[1])] };
+                if ("beginsWith" in cond)
+                    return { beginsWith: rewrite(cond.beginsWith) };
+                return cond;
+            };
+            const bqConfig = {
+                pathBuilder,
+                conditionOps,
+                provide,
+                skFields: orderBy ? [orderBy] : [],
+                composeSkCondition,
+            };
+            return new BoundQueryImpl(q, bqConfig);
+        },
         // Query execution
         paginate: (q, ...combinators) => {
             const final = applyQuery(q, combinators);