@react-text-game/core 0.1.0

package/dist/storage.js

@@ -0,0 +1,229 @@
+import { JSONPath } from "jsonpath-plus";
+import { STORAGE_SYSTEM_PATH } from "./constants";
+const storage = {};
+/**
+ * JSONPath-based storage system for game state persistence.
+ *
+ * The Storage class provides a flexible way to store and retrieve game state using
+ * JSONPath queries. It supports nested data structures and protects system paths
+ * from accidental modification.
+ *
+ * @see https://www.npmjs.com/package/jsonpath-plus - JSONPath Plus library documentation
+ *
+ * @example
+ * ```typescript
+ * // Set values
+ * Storage.setValue('$.player.health', 100);
+ * Storage.setValue('$.inventory.items', ['sword', 'shield']);
+ *
+ * // Get values
+ * const health = Storage.getValue<number>('$.player.health');
+ * const items = Storage.getValue<string[]>('$.inventory.items');
+ *
+ * // Full state
+ * const state = Storage.getState();
+ * Storage.setState(state);
+ * ```
+ */
+export class Storage {
+    /**
+     * Retrieves values from storage using a JSONPath query.
+     *
+     * Returns an array of matching values. If no matches are found, returns an empty array.
+     * The JSONPath Plus library supports complex queries including wildcards, filters, and deep scanning.
+     *
+     * @template T - The expected type of values to retrieve
+     * @param jsonPath - The JSONPath query string (e.g., '$.player.health', '$.inventory.items[*]')
+     * @returns Array of values matching the JSONPath query
+     *
+     * @example
+     * ```typescript
+     * // Get a single value (returns array with one element)
+     * const health = Storage.getValue<number>('$.player.health');
+     * if (health.length > 0) {
+     *   console.log(health[0]); // 100
+     * }
+     *
+     * // Get multiple values with wildcard
+     * const allItems = Storage.getValue<string>('$.inventory.*.name');
+     * ```
+     */
+    static getValue(jsonPath) {
+        return JSONPath({ path: jsonPath, json: storage });
+    }
+    /**
+     * Sets a value in storage at the specified JSONPath.
+     *
+     * If the path exists, updates the value. If the path doesn't exist, creates it.
+     * System paths (prefixed with STORAGE_SYSTEM_PATH) are protected from external modification.
+     *
+     * @template T - The type of value to set
+     * @param jsonPath - The JSONPath where the value should be set
+     * @param value - The value to set at the specified JSONPath
+     * @param _isSystem - Internal flag to allow system path modification (default: false)
+     * @throws Error if attempting to modify a system path without _isSystem flag
+     *
+     * @example
+     * ```typescript
+     * // Set a simple value
+     * Storage.setValue('$.player.health', 75);
+     *
+     * // Set a complex object
+     * Storage.setValue('$.player.stats', { str: 10, dex: 8 });
+     *
+     * // System paths are protected
+     * Storage.setValue('$._system.game', {}); // Throws error
+     * ```
+     */
+    static setValue(jsonPath, value, _isSystem = false) {
+        if (jsonPath.includes(STORAGE_SYSTEM_PATH) && !_isSystem) {
+            throw new Error(`Cannot set value at system path: ${jsonPath}`);
+        }
+        // Check if the path exists
+        const existingValues = JSONPath({
+            path: jsonPath,
+            json: storage,
+        });
+        if (existingValues.length > 0) {
+            // Path exists, update it
+            const parents = JSONPath({
+                path: jsonPath,
+                json: storage,
+                resultType: "parent",
+            });
+            const properties = JSONPath({
+                path: jsonPath,
+                json: storage,
+                resultType: "parentProperty",
+            });
+            // Update all matching paths
+            for (let i = 0; i < parents.length; i++) {
+                parents[i][properties[i]] = value;
+            }
+        }
+        else {
+            // Path doesn't exist, create it
+            this.createPath(storage, jsonPath, value);
+        }
+    }
+    /**
+     * Retrieves the entire storage state as a plain object.
+     *
+     * @returns The complete storage state, ready for serialization
+     *
+     * @example
+     * ```typescript
+     * const state = Storage.getState();
+     * localStorage.setItem('save', JSON.stringify(state));
+     * ```
+     */
+    static getState() {
+        return storage;
+    }
+    /**
+     * Replaces the entire storage state with a new state object.
+     *
+     * Clears all existing storage data and replaces it with the provided state.
+     * Useful for loading saved games or resetting to a specific state.
+     *
+     * @param state - The new state to set for the storage
+     * @throws Error if state is not a valid object
+     *
+     * @example
+     * ```typescript
+     * const savedState = JSON.parse(localStorage.getItem('save'));
+     * Storage.setState(savedState);
+     * ```
+     */
+    static setState(state) {
+        if (typeof state !== "object" || state === null) {
+            throw new Error("Invalid state provided. Expected an object.");
+        }
+        // Clear the current storage
+        for (const key in storage) {
+            delete storage[key];
+        }
+        // Set the new state
+        Object.assign(storage, state);
+    }
+    /**
+     * Creates a nested path in storage and assigns a value.
+     *
+     * Parses the JSONPath and creates all necessary intermediate objects/arrays
+     * to build the path if it doesn't exist. Supports both object properties and array indices.
+     *
+     * @private - Used internally by setValue when creating new paths
+     * @template T - The type of value to set at the path
+     * @param obj - The target object where the path will be created
+     * @param jsonPath - The JSONPath string specifying the location
+     * @param value - The value to set at the specified location
+     *
+     * @example
+     * ```typescript
+     * // Creates $.player.inventory.items[0] = 'sword'
+     * // Will create player object, inventory object, items array automatically
+     * Storage.createPath(storage, '$.player.inventory.items[0]', 'sword');
+     * ```
+     */
+    static createPath(obj, jsonPath, value) {
+        // Parse the JSONPath to get the path components
+        // toPathArray converts '$.a.b[0]' to ['$', 'a', 'b', '0']
+        const pathComponents = JSONPath.toPathArray(jsonPath);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let current = obj;
+        // Iterate through path components, skipping the root ($)
+        for (let i = 1; i < pathComponents.length; i++) {
+            const component = pathComponents[i];
+            if (!component) {
+                throw new Error(`Invalid path component at index ${i} in path: ${jsonPath}`);
+            }
+            const isLast = i === pathComponents.length - 1;
+            // Check if the component is a numeric array index
+            const isNumeric = /^\d+$/.test(component);
+            if (isNumeric) {
+                // Array index like [0] or [1]
+                const index = parseInt(component);
+                if (isLast) {
+                    // Ensure current is an array
+                    if (!Array.isArray(current)) {
+                        throw new Error(`Cannot set array index on non-array at path: ${jsonPath}`);
+                    }
+                    current[index] = value;
+                }
+                else {
+                    // Create array if it doesn't exist or extend it if needed
+                    if (!Array.isArray(current)) {
+                        throw new Error(`Cannot access array index on non-array at path: ${jsonPath}`);
+                    }
+                    if (!current[index]) {
+                        // Look ahead to see if next component is numeric
+                        const nextComponent = pathComponents[i + 1];
+                        const nextIsNumeric = nextComponent && /^\d+$/.test(nextComponent);
+                        current[index] = nextIsNumeric ? [] : {};
+                    }
+                    current = current[index];
+                }
+            }
+            else {
+                // Property access like .hello or .user
+                const key = component;
+                if (isLast) {
+                    current[key] = value;
+                }
+                else {
+                    // Create object or array if it doesn't exist
+                    if (!(key in current) ||
+                        typeof current[key] !== "object" ||
+                        current[key] === null) {
+                        // Look ahead to see if next component is numeric (array index)
+                        const nextComponent = pathComponents[i + 1];
+                        const nextIsNumeric = nextComponent && /^\d+$/.test(nextComponent);
+                        current[key] = nextIsNumeric ? [] : {};
+                    }
+                    current = current[key];
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/tests/game.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=game.test.d.ts.map

package/dist/tests/game.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.test.d.ts","sourceRoot":"","sources":["../../src/tests/game.test.ts"],"names":[],"mappings":""}