@stackedapp/utils 1.15.5 → 1.15.7

package/dist/apply_delta.d.ts

@@ -0,0 +1,60 @@
+import { PlayerDelta, StackedSnapshot, StackedOffer } from '@stackedapp/types';
+/**
+ * Apply a PlayerDelta to a target object (StackedSnapshot or StackedOffer).
+ * Mutates the target object in place and returns it.
+ *
+ * @param target - The object to apply the delta to
+ * @param delta - The delta operations to apply
+ * @returns The mutated target object
+ *
+ * @example
+ * ```typescript
+ * // Apply snapshot delta
+ * const snapshot = { currencies: { gold: { balance: 100 } } };
+ * applyDelta(snapshot, {
+ *   target: 'snapshot',
+ *   inc: { 'currencies.gold.balance': 50 }
+ * });
+ * // snapshot.currencies.gold.balance is now 150
+ *
+ * // Apply offer delta
+ * const offer = { completionTrackers: { buyItem: 5 } };
+ * applyDelta(offer, {
+ *   target: 'offers',
+ *   offers: ['offer-123'],
+ *   inc: { 'completionTrackers.buyItem': 3 }
+ * });
+ * // offer.completionTrackers.buyItem is now 8
+ * ```
+ */
+export declare function applyDelta<T extends StackedSnapshot | StackedOffer>(target: T, delta: PlayerDelta): T;
+/**
+ * Apply a PlayerDelta to a StackedSnapshot.
+ * Convenience wrapper with correct typing.
+ */
+export declare function applySnapshotDelta(snapshot: StackedSnapshot, delta: PlayerDelta): StackedSnapshot;
+/**
+ * Apply a PlayerDelta to a StackedOffer.
+ * Convenience wrapper with correct typing.
+ *
+ * Note: For offer deltas, check delta.offers to see if this offer is affected.
+ */
+export declare function applyOfferDelta(offer: StackedOffer, delta: PlayerDelta): StackedOffer;
+/**
+ * Check if an offer is affected by a delta.
+ * Use this to filter which offers need updating.
+ *
+ * @param offerId - The offer's instanceId to check
+ * @param delta - The delta to check against
+ * @returns true if this offer is in the delta's affected offers list
+ */
+export declare function isOfferAffectedByDelta(offerId: string, delta: PlayerDelta): boolean;
+/**
+ * Apply a delta to multiple offers, only updating affected ones.
+ *
+ * @param offers - Map of offerId to StackedOffer
+ * @param delta - The delta to apply
+ * @returns Array of offerIds that were updated
+ */
+export declare function applyDeltaToOffers(offers: Map<string, StackedOffer> | Record<string, StackedOffer>, delta: PlayerDelta): string[];
+//# sourceMappingURL=apply_delta.d.ts.map

package/dist/apply_delta.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyDelta = applyDelta;
+exports.applySnapshotDelta = applySnapshotDelta;
+exports.applyOfferDelta = applyOfferDelta;
+exports.isOfferAffectedByDelta = isOfferAffectedByDelta;
+exports.applyDeltaToOffers = applyDeltaToOffers;
+/**
+ * Get a nested value from an object using a dot-separated path.
+ * e.g., getNestedValue(obj, 'currencies.gold.balance')
+ */
+function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current == null)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Set a nested value in an object using a dot-separated path.
+ * Creates intermediate objects as needed.
+ * e.g., setNestedValue(obj, 'currencies.gold.balance', 100)
+ */
+function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] == null || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[keys[keys.length - 1]] = value;
+}
+/**
+ * Delete a nested value from an object using a dot-separated path.
+ * e.g., deleteNestedValue(obj, 'currencies.gold')
+ */
+function deleteNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] == null)
+            return;
+        current = current[key];
+    }
+    delete current[keys[keys.length - 1]];
+}
+/**
+ * Determine the unique key field for array item matching.
+ * Used for addToSet and pull operations.
+ */
+function getArrayItemKey(fieldPath) {
+    const field = fieldPath.split('.').pop();
+    switch (field) {
+        case 'cryptoWallets':
+            return 'address';
+        case 'identifiers':
+            return 'identifier';
+        case 'entityLinks':
+            return 'playerId';
+        case 'tags':
+            return null; // Simple string array - match by value directly
+        default:
+            // For unknown arrays, try common keys
+            return null;
+    }
+}
+/**
+ * Check if two items match based on criteria.
+ * For objects: match if all criteria fields match.
+ * For primitives: match if equal.
+ */
+function itemMatchesCriteria(item, criteria) {
+    if (typeof criteria !== 'object' || criteria === null) {
+        // Primitive comparison (e.g., tags array)
+        return item === criteria;
+    }
+    if (typeof item !== 'object' || item === null) {
+        return false;
+    }
+    // Object comparison - all criteria fields must match
+    for (const [key, value] of Object.entries(criteria)) {
+        if (item[key] !== value) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Check if an item already exists in an array (for addToSet deduplication).
+ */
+function itemExistsInArray(array, newItem, keyField) {
+    if (keyField === null) {
+        // Simple value comparison (e.g., tags)
+        return array.includes(newItem);
+    }
+    // Object comparison by key field
+    if (typeof newItem !== 'object' || newItem === null) {
+        return array.includes(newItem);
+    }
+    const newKeyValue = newItem[keyField];
+    return array.some((existing) => {
+        if (typeof existing !== 'object' || existing === null)
+            return false;
+        return existing[keyField] === newKeyValue;
+    });
+}
+/**
+ * Apply a PlayerDelta to a target object (StackedSnapshot or StackedOffer).
+ * Mutates the target object in place and returns it.
+ *
+ * @param target - The object to apply the delta to
+ * @param delta - The delta operations to apply
+ * @returns The mutated target object
+ *
+ * @example
+ * ```typescript
+ * // Apply snapshot delta
+ * const snapshot = { currencies: { gold: { balance: 100 } } };
+ * applyDelta(snapshot, {
+ *   target: 'snapshot',
+ *   inc: { 'currencies.gold.balance': 50 }
+ * });
+ * // snapshot.currencies.gold.balance is now 150
+ *
+ * // Apply offer delta
+ * const offer = { completionTrackers: { buyItem: 5 } };
+ * applyDelta(offer, {
+ *   target: 'offers',
+ *   offers: ['offer-123'],
+ *   inc: { 'completionTrackers.buyItem': 3 }
+ * });
+ * // offer.completionTrackers.buyItem is now 8
+ * ```
+ */
+function applyDelta(target, delta) {
+    // Apply $set operations
+    if (delta.set) {
+        for (const [path, value] of Object.entries(delta.set)) {
+            setNestedValue(target, path, value);
+        }
+    }
+    // Apply $inc operations
+    if (delta.inc) {
+        for (const [path, amount] of Object.entries(delta.inc)) {
+            const current = getNestedValue(target, path);
+            const currentNum = typeof current === 'number' ? current : 0;
+            setNestedValue(target, path, currentNum + amount);
+        }
+    }
+    // Apply $min operations
+    if (delta.min) {
+        for (const [path, value] of Object.entries(delta.min)) {
+            const current = getNestedValue(target, path);
+            if (typeof current !== 'number') {
+                setNestedValue(target, path, value);
+            }
+            else {
+                setNestedValue(target, path, Math.min(current, value));
+            }
+        }
+    }
+    // Apply $max operations
+    if (delta.max) {
+        for (const [path, value] of Object.entries(delta.max)) {
+            const current = getNestedValue(target, path);
+            if (typeof current !== 'number') {
+                setNestedValue(target, path, value);
+            }
+            else {
+                setNestedValue(target, path, Math.max(current, value));
+            }
+        }
+    }
+    // Apply $unset operations
+    if (delta.unset) {
+        for (const path of delta.unset) {
+            deleteNestedValue(target, path);
+        }
+    }
+    // Apply $pull operations BEFORE addToSet/push
+    // This is critical for the identifier_link pattern where we:
+    // 1. Remove existing item (pull)
+    // 2. Add updated item (addToSet)
+    // If addToSet ran first, it would see the duplicate and not add.
+    if (delta.pull) {
+        for (const [path, criteriaList] of Object.entries(delta.pull)) {
+            const current = getNestedValue(target, path);
+            if (!Array.isArray(current)) {
+                continue;
+            }
+            const array = current;
+            // Filter out items that match ANY of the criteria
+            const filtered = array.filter((item) => !criteriaList.some((criteria) => itemMatchesCriteria(item, criteria)));
+            setNestedValue(target, path, filtered);
+        }
+    }
+    // Apply $addToSet operations (add unique items to array)
+    if (delta.addToSet) {
+        for (const [path, items] of Object.entries(delta.addToSet)) {
+            const keyField = getArrayItemKey(path);
+            let current = getNestedValue(target, path);
+            if (!Array.isArray(current)) {
+                current = [];
+                setNestedValue(target, path, current);
+            }
+            const array = current;
+            for (const item of items) {
+                if (!itemExistsInArray(array, item, keyField)) {
+                    array.push(item);
+                }
+            }
+        }
+    }
+    // Apply $push operations (append to array, allows duplicates)
+    if (delta.push) {
+        for (const [path, items] of Object.entries(delta.push)) {
+            let current = getNestedValue(target, path);
+            if (!Array.isArray(current)) {
+                current = [];
+                setNestedValue(target, path, current);
+            }
+            const array = current;
+            array.push(...items);
+        }
+    }
+    return target;
+}
+/**
+ * Apply a PlayerDelta to a StackedSnapshot.
+ * Convenience wrapper with correct typing.
+ */
+function applySnapshotDelta(snapshot, delta) {
+    if (delta.target !== 'snapshot') {
+        console.warn('applySnapshotDelta called with non-snapshot delta target:', delta.target);
+    }
+    return applyDelta(snapshot, delta);
+}
+/**
+ * Apply a PlayerDelta to a StackedOffer.
+ * Convenience wrapper with correct typing.
+ *
+ * Note: For offer deltas, check delta.offers to see if this offer is affected.
+ */
+function applyOfferDelta(offer, delta) {
+    if (delta.target !== 'offers') {
+        console.warn('applyOfferDelta called with non-offers delta target:', delta.target);
+    }
+    return applyDelta(offer, delta);
+}
+/**
+ * Check if an offer is affected by a delta.
+ * Use this to filter which offers need updating.
+ *
+ * @param offerId - The offer's instanceId to check
+ * @param delta - The delta to check against
+ * @returns true if this offer is in the delta's affected offers list
+ */
+function isOfferAffectedByDelta(offerId, delta) {
+    if (delta.target !== 'offers')
+        return false;
+    if (!delta.offers)
+        return false;
+    return delta.offers.includes(offerId);
+}
+/**
+ * Apply a delta to multiple offers, only updating affected ones.
+ *
+ * @param offers - Map of offerId to StackedOffer
+ * @param delta - The delta to apply
+ * @returns Array of offerIds that were updated
+ */
+function applyDeltaToOffers(offers, delta) {
+    if (delta.target !== 'offers' || !delta.offers) {
+        return [];
+    }
+    const updated = [];
+    const offerMap = offers instanceof Map ? offers : new Map(Object.entries(offers));
+    for (const offerId of delta.offers) {
+        const offer = offerMap.get(offerId);
+        if (offer) {
+            applyDelta(offer, delta);
+            updated.push(offerId);
+        }
+    }
+    return updated;
+}
+//# sourceMappingURL=apply_delta.js.map

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from './blockchain_utils';
 export { default as currency } from './currency';
 export * from './player_data';
 export * from './player_snapshot';
+export * from './apply_delta';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -26,4 +26,5 @@ var currency_1 = require("./currency");
 Object.defineProperty(exports, "currency", { enumerable: true, get: function () { return __importDefault(currency_1).default; } });
 __exportStar(require("./player_data"), exports);
 __exportStar(require("./player_snapshot"), exports);
+__exportStar(require("./apply_delta"), exports);
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackedapp/utils",
-  "version": "1.15.5",
+  "version": "1.15.7",
   "description": "Public utilities for Stacked platform SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",