@aligent/appbuilder-util-lib 0.2.0 → 0.2.1

package/docs/functions/createDatabaseStorageClient.md

@@ -0,0 +1,135 @@
+[**@aligent/appbuilder-util-lib**](../modules.md)
+
+***
+
+[@aligent/appbuilder-util-lib](../modules.md) / [aio-persistent-state](../modules/aio-persistent-state.md) / createDatabaseStorageClient
+
+# Function: createDatabaseStorageClient()
+
+> **createDatabaseStorageClient**\<`T`\>(`config`): `DatabaseStorageClient<T>`
+
+Creates a hybrid State + Database storage client for typed JSON objects.
+
+Each client manages ONE document identified by `dbDocumentId`. Calling `put()` will overwrite any existing data. For storing multiple items, create separate clients with different `key` and `dbDocumentId` values.
+
+All clients share the same underlying Adobe I/O State and Database instances — they are lightweight wrappers that provide typed access to specific documents.
+
+## Type Parameters
+
+### T
+
+`T extends Document`
+
+The type of data to store. Must be JSON-serializable.
+
+## Parameters
+
+### config
+
+`DatabaseStorageClientConfig<T>`
+
+Configuration options for the client.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `key` | `string` | Yes | Key for State cache |
+| `dbCollection` | `string` | Yes | Database collection name |
+| `dbDocumentId` | `string` | Yes | Document ID in the collection |
+| `ttl` | `number` | No | State cache TTL in seconds (default: 31,536,000 = 1 year) |
+
+## Returns
+
+`DatabaseStorageClient<T>`
+
+A client object with `put`, `get`, `exists`, and `delete` methods.
+
+### Methods
+
+#### `put(data, logger?): Promise<void>`
+
+Stores a typed object. Data is JSON-serialized for State and stored as a native document in Database.
+
+#### `get(logger?): Promise<T | undefined>`
+
+Retrieves the stored object. Returns `undefined` if not found.
+
+#### `exists(logger?): Promise<boolean>`
+
+Checks if data exists without returning it.
+
+#### `delete(logger?): Promise<void>`
+
+Deletes data from both State and Database.
+
+## Example
+
+```typescript
+import { createDatabaseStorageClient } from '@aligent/appbuilder-util-lib';
+
+// Define your data type
+interface UserPreferences {
+  theme: 'light' | 'dark';
+  notifications: boolean;
+  language: string;
+}
+
+const prefsClient = createDatabaseStorageClient<UserPreferences>({
+  key: 'user-prefs',
+  dbCollection: 'preferences',
+  dbDocumentId: 'user-123',
+  ttl: 86400, // Optional: 1 day TTL
+});
+
+// Store typed data
+await prefsClient.put({
+  theme: 'dark',
+  notifications: true,
+  language: 'en',
+});
+
+// Retrieve typed data (returns UserPreferences | undefined)
+const prefs = await prefsClient.get();
+if (prefs) {
+  console.log(prefs.theme); // TypeScript knows this is 'light' | 'dark'
+}
+
+// Check existence
+if (await prefsClient.exists()) {
+  console.log('Preferences exist');
+}
+
+// Delete data
+await prefsClient.delete();
+```
+
+## Behaviour
+
+### Storage format
+
+Data is stored differently in each tier:
+
+| Operation | State | Database |
+|-----------|-------|----------|
+| `put(data)` | `JSON.stringify(data)` → stored as string | `{ _id, ...data }` → stored as native document |
+| `get()` | `JSON.parse(value)` → returned as object | Remove `_id` → returned as object |
+
+### 1 MB State size limit
+
+Values exceeding 1 MB (when JSON-serialized) are stored in Database only. On read, such values are returned without being cached in State.
+
+### Read flow
+
+1. Try State first (fast, but subject to TTL expiry)
+2. On cache miss, fall back to Database (persistent, no TTL)
+3. Self-heal: restore data to State for future reads (if within 1 MB limit)
+
+### Write flow
+
+1. Write to Database first (durability)
+2. Cache in State (if within 1 MB limit)
+
+## Notes
+
+- Data must be JSON-serializable (no `Date` objects, `Map`, `Set`, `BigInt`, or circular references without custom handling)
+- Adobe I/O Database uses AWS DocumentDB (MongoDB-compatible) under the hood
+- The `_id` field is automatically managed; do not include it in your data type

package/docs/functions/createFileStorageClient.md

@@ -0,0 +1,102 @@
+[**@aligent/appbuilder-util-lib**](../modules.md)
+
+***
+
+[@aligent/appbuilder-util-lib](../modules.md) / [aio-persistent-state](../modules/aio-persistent-state.md) / createFileStorageClient
+
+# Function: createFileStorageClient()
+
+> **createFileStorageClient**(`config`): `FileStorageClient`
+
+Creates a hybrid State + Files storage client for string data.
+
+Each client manages ONE key. Calling `put()` will overwrite any existing data. For storing multiple items, create separate clients with different `key` values.
+
+All clients share the same underlying Adobe I/O State and Files instances — they are lightweight wrappers that provide typed access to specific keys.
+
+## Parameters
+
+### config
+
+`FileStorageClientConfig`
+
+Configuration options for the client.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `key` | `string` | Yes | Unique identifier for the data in State and Files storage |
+| `ttl` | `number` | No | State cache TTL in seconds (default: 31,536,000 = 1 year) |
+
+## Returns
+
+`FileStorageClient`
+
+A client object with `put`, `get`, `exists`, and `delete` methods.
+
+### Methods
+
+#### `put(value, logger?): Promise<void>`
+
+Stores a string value. Values exceeding 1 MB are stored in Files only (State is skipped).
+
+#### `get(logger?): Promise<string | undefined>`
+
+Retrieves the stored value. Returns `undefined` if not found.
+
+#### `exists(logger?): Promise<boolean>`
+
+Checks if data exists without returning it.
+
+#### `delete(logger?): Promise<void>`
+
+Deletes data from both State and Files.
+
+## Example
+
+```typescript
+import { createFileStorageClient } from '@aligent/appbuilder-util-lib';
+
+const configClient = createFileStorageClient({
+  key: 'app-config',
+  ttl: 86400, // Optional: 1 day TTL
+});
+
+// Store a JSON string
+await configClient.put(JSON.stringify({ theme: 'dark', locale: 'en' }));
+
+// Retrieve the value (returns string | undefined)
+const config = await configClient.get();
+if (config) {
+  console.log(JSON.parse(config)); // { theme: 'dark', locale: 'en' }
+}
+
+// Check existence
+if (await configClient.exists()) {
+  console.log('Config exists');
+}
+
+// Delete data
+await configClient.delete();
+```
+
+## Behaviour
+
+### 1 MB State size limit
+
+Adobe I/O State imposes a maximum value size of 1 MB per entry. This client handles it automatically:
+
+- **On write (`put`)**: Values exceeding 1 MB are stored in Files only; State is skipped with a warning log.
+- **On read (`get`)**: If the value from Files exceeds 1 MB, it is returned directly without being cached in State.
+
+Values within the 1 MB limit are stored in both layers so that subsequent reads are served from the faster State cache.
+
+### Read flow
+
+1. Try State first (fast, but subject to TTL expiry)
+2. On cache miss, fall back to Files (persistent, no TTL)
+3. Self-heal: restore data to State for future reads (if within 1 MB limit)
+
+### Write flow
+
+1. Write to Files first (durability)
+2. Cache in State (if within 1 MB limit)

package/docs/modules/aio-persistent-state.md

@@ -6,34 +6,61 @@
 
 # Module: aio-persistent-state
 
-A utility library for persistent, high-performance key-value storage
-using Adobe I/O State (for caching) and Adobe I/O File (for durability).
+A utility library for persistent, high-performance key-value storage in Adobe App Builder runtime. Provides two hybrid storage clients:
+
+- **State + Files** — for string data up to 1 MB with automatic overflow handling
+- **State + Database** — for typed JSON objects with MongoDB-like storage
 
 ## Overview
 
-This library provides a high-level abstraction for key-value storage using Adobe App Builder's runtime services. It combines:
-- **Adobe I/O Lib State** — fast access and short-term caching
-- **Adobe I/O Lib Files** — long-term durability and backup
+This library provides high-level abstractions for key-value storage using Adobe App Builder's runtime services. Both clients use a two-tier architecture:
 
-### Why both State and Files?
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  State (fast, TTL-based)  ←──cache──→  Files/Database (permanent)       │
+└─────────────────────────────────────────────────────────────────────────┘
+```
 
-Adobe I/O State enforces a **TTL (Time-To-Live)** on all entries, so cached data will eventually expire and be evicted. Files storage has no such expiration, making it suitable for persistent, long-lived data. By writing to Files for durability and using State as a fast-access cache, we get speed from State and persistence from Files.
+### Why two tiers?
 
-### 1 MB State size limit
+Adobe I/O State enforces a **TTL (Time-To-Live)** on all entries, so cached data will eventually expire. Files and Database storage have no such expiration, making them suitable for persistent data. By combining both, we get speed from State and persistence from the durable tier.
 
-Adobe I/O State imposes a **maximum value size of 1 MB** per entry. This library works around the limit automatically:
-- **On write (`put`)**: values exceeding 1 MB are stored in Files only; the State cache is skipped.
-- **On read (`get`)**: if the value retrieved from Files exceeds 1 MB, it is returned directly without being cached in State.
+### Storage options
 
-Values within the 1 MB limit are stored in both layers so that subsequent reads are served from the faster State cache.
+| Feature        | State + Files             | State + Database                |
+|----------------|---------------------------|---------------------------------|
+| Data type      | `string`                  | Generic `T` (JSON-serializable) |
+| Max value size | Unlimited (1 MB cached)   | Limited by Database             |
+| Query support  | Key-based only            | MongoDB-like queries            |
+| Best for       | Large strings, JSON blobs | Structured typed data           |
 
-### How it works
+## Interfaces
 
-- Data is retrieved quickly from State if present (cache hit)
-- If not found in State (cache miss, e.g. due to TTL expiry), the library loads from Files, then re-populates the State cache
-- On updates, the value is written to Files first for durability, then cached in State
+- [FileStorageClientConfig](../interfaces/FileStorageClientConfig.md)
+- [FileStorageClient](../interfaces/FileStorageClient.md)
+- [DatabaseStorageClientConfig](../interfaces/DatabaseStorageClientConfig.md)
+- [DatabaseStorageClient](../interfaces/DatabaseStorageClient.md)
 
 ## Functions
 
-- [PersistentState.get](../functions/get.md)
-- [PersistentState.put](../functions/put.md)
+- [createFileStorageClient](../functions/createFileStorageClient.md)
+- [createDatabaseStorageClient](../functions/createDatabaseStorageClient.md)
+
+## Behaviour
+
+### Read flow
+
+1. Try State first (fast path)
+2. On cache miss, fall back to Files/Database
+3. Self-heal: restore data to State cache for future reads
+
+### Write flow
+
+- **Files client**: Write to Files first (durability), then cache in State
+- **Database client**: Write to Database first, then cache in State
+
+### Error handling
+
+- `get()` returns `undefined` when data is not found
+- All methods throw on actual storage errors (connection failures, etc.)
+- Errors are logged before being re-thrown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/appbuilder-util-lib",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A utility library to simplify and standardise common Adobe App Builder tasks.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -11,10 +11,16 @@
     "directory": "packages/appbuilder-util-lib"
   },
   "dependencies": {
-    "@adobe/aio-sdk": "^6.0.0",
+    "@adobe/aio-lib-core-logging": "^3.0.2",
+    "@adobe/aio-lib-db": "^0.1.0-beta.6",
+    "@adobe/aio-lib-files": "^4.1.2",
+    "@adobe/aio-lib-state": "^5.3.1",
     "base64url": "^3.0.1"
   },
   "author": "Aligent",
   "license": "MIT",
+  "devDependencies": {
+    "mongodb": "^7.1.0"
+  },
   "types": "./src/index.d.ts"
 }

package/src/aio-persistent-state/constants.d.ts

@@ -0,0 +1,6 @@
+/** Default TTL for I/O State: 1 year in seconds (maximum allowed by Adobe I/O State) */
+export declare const DEFAULT_ONE_YEAR_TTL_SECONDS = 31536000;
+/** Maximum length (in characters) of a base64url-encoded key accepted by State. */
+export declare const MAX_KEY_SIZE = 1024;
+/** Maximum value size (in bytes) accepted by Adobe I/O State (1 MB). */
+export declare const MAX_STATE_VALUE_SIZE: number;

package/src/aio-persistent-state/constants.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_STATE_VALUE_SIZE = exports.MAX_KEY_SIZE = exports.DEFAULT_ONE_YEAR_TTL_SECONDS = void 0;
+/** Default TTL for I/O State: 1 year in seconds (maximum allowed by Adobe I/O State) */
+exports.DEFAULT_ONE_YEAR_TTL_SECONDS = 31536000;
+/** Maximum length (in characters) of a base64url-encoded key accepted by State. */
+exports.MAX_KEY_SIZE = 1024;
+/** Maximum value size (in bytes) accepted by Adobe I/O State (1 MB). */
+exports.MAX_STATE_VALUE_SIZE = 1024 * 1024; // 1MB

package/src/aio-persistent-state/index.d.ts

@@ -0,0 +1,2 @@
+export * from './state-database';
+export * from './state-files';

package/src/aio-persistent-state/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./state-database"), exports);
+__exportStar(require("./state-files"), exports);

package/src/aio-persistent-state/state-database.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module aio-persistent-state/database
+ *
+ * A two-tier key-value storage library for Adobe App Builder runtime that
+ * combines Adobe I/O State and Adobe I/O Database to achieve both fast access
+ * and long-term durability.
+ *
+ * **Why both State and Database?**
+ * Adobe I/O State enforces a TTL (Time-To-Live) on all entries, meaning
+ * cached data will expire and be evicted automatically. Database storage has
+ * no such expiration, making it suitable for persistent, long-lived data.
+ * By writing to Database for durability and using State as a fast-access cache,
+ * we get the best of both: speed from State and persistence from Database.
+ *
+ * **Architecture:**
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │  State (fast, TTL-based)  ←──cache──→  Database (permanent backup)      │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * **Write flow:** Database first and then State if the value is within the State size limit (1MB).
+ * **Read flow:** State first → Database fallback → self-heal (restore to State)
+ *
+ * @see https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/storage/database
+ */
+import AioLogger from '@adobe/aio-lib-core-logging';
+import { type Document, type InferIdType } from '@adobe/aio-lib-db';
+/**
+ * Configuration options for creating a database storage client.
+ */
+export interface DatabaseStorageClientConfig<T> {
+    /** Key used to store data in Adobe I/O State */
+    key: string;
+    /** Collection name in Adobe I/O Database */
+    dbCollection: string;
+    /** Document ID in the database collection */
+    dbDocumentId: InferIdType<T & {
+        _id: string;
+    }>;
+    /** TTL (time-to-live) for State storage in seconds. Default: 31536000 (1 year) */
+    ttl?: number;
+}
+/**
+ * Interface for a hybrid State + database storage client.
+ */
+export interface DatabaseStorageClient<T extends Document> {
+    /**
+     * Save data to both State and Database.
+     * Values exceeding 1MB are stored in Database only.
+     */
+    put(data: T, logger?: ReturnType<typeof AioLogger>): Promise<void>;
+    /**
+     * Retrieve data using State-first, Database-fallback strategy.
+     * Includes self-healing: restores to State if found in Database and if the value is within the 1MB size limit.
+     * `undefined` is returned if no data is found.
+     */
+    get(logger?: ReturnType<typeof AioLogger>): Promise<T | undefined>;
+    /**
+     * Check if data exists without returning it.
+     */
+    exists(logger?: ReturnType<typeof AioLogger>): Promise<boolean>;
+    /**
+     * Delete data from both State and Database.
+     */
+    delete(logger?: ReturnType<typeof AioLogger>): Promise<void>;
+    /** The configuration used to create this client */
+    readonly config: Readonly<Required<DatabaseStorageClientConfig<T>>>;
+}
+/**
+ * Create a hybrid storage client to manage a single document of a specific data type.
+ *
+ * Each client manages ONE document identified by `dbDocumentId`. Calling `put()`
+ * will overwrite any existing data. For storing multiple items, create separate
+ * clients with different `key` and `dbDocumentId` values.
+ *
+ * All clients share the same underlying Adobe I/O State and Database - they are
+ * lightweight wrappers that provide typed access to specific documents.
+ *
+ * The client provides `put`, `get`, `exists`, and `delete` functions to manage data.
+ *
+ * @example
+ * ```typescript
+ * interface UserPreferences {
+ *   theme: 'light' | 'dark';
+ *   notifications: boolean;
+ * }
+ *
+ * // Each client manages a single document in the shared storage
+ * const prefsClient = createDatabaseStorageClient<UserPreferences>({
+ *   key: 'user-prefs',
+ *   dbCollection: 'preferences',
+ *   dbDocumentId: 'user-prefs',  // Fixed document ID - only one document per client
+ * });
+ *
+ * // Save preferences (overwrites any existing data)
+ * await prefsClient.put({ theme: 'dark', notifications: true });
+ *
+ * // Retrieve preferences
+ * const prefs = await prefsClient.get();
+ * if (prefs) {
+ *   console.log('Theme:', prefs.theme); // Output: "Theme: dark"
+ * }
+ * ```
+ */
+export declare function createDatabaseStorageClient<T extends Document>(config: DatabaseStorageClientConfig<T>): DatabaseStorageClient<T>;

package/src/aio-persistent-state/state-database.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * @module aio-persistent-state/database
+ *
+ * A two-tier key-value storage library for Adobe App Builder runtime that
+ * combines Adobe I/O State and Adobe I/O Database to achieve both fast access
+ * and long-term durability.
+ *
+ * **Why both State and Database?**
+ * Adobe I/O State enforces a TTL (Time-To-Live) on all entries, meaning
+ * cached data will expire and be evicted automatically. Database storage has
+ * no such expiration, making it suitable for persistent, long-lived data.
+ * By writing to Database for durability and using State as a fast-access cache,
+ * we get the best of both: speed from State and persistence from Database.
+ *
+ * **Architecture:**
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │  State (fast, TTL-based)  ←──cache──→  Database (permanent backup)      │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * **Write flow:** Database first and then State if the value is within the State size limit (1MB).
+ * **Read flow:** State first → Database fallback → self-heal (restore to State)
+ *
+ * @see https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/storage/database
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDatabaseStorageClient = createDatabaseStorageClient;
+const aio_lib_db_1 = require("@adobe/aio-lib-db");
+const aio_lib_state_1 = require("@adobe/aio-lib-state");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+let stateLibPromise;
+let dbLibPromise;
+/**
+ * Returns a lazily-initialised Adobe I/O State instance.
+ * The promise is cached so the SDK is only initialised once per process.
+ * If initialisation fails, the cache is cleared so the next call retries.
+ *
+ * @returns A promise that resolves to the Adobe I/O State instance.
+ */
+function getStateLib() {
+    stateLibPromise ??= (0, aio_lib_state_1.init)().catch(err => {
+        stateLibPromise = undefined;
+        throw err;
+    });
+    return stateLibPromise;
+}
+/**
+ * Returns a lazily-initialised Adobe I/O Database instance.
+ * The promise is cached so the SDK is only initialised once per process.
+ * If initialisation fails, the cache is cleared so the next call retries.
+ *
+ * @returns A promise that resolves to the Adobe I/O Database instance.
+ */
+function getDbLib() {
+    dbLibPromise ??= (0, aio_lib_db_1.init)().catch(err => {
+        dbLibPromise = undefined;
+        throw err;
+    });
+    return dbLibPromise;
+}
+/**
+ * Create a hybrid storage client to manage a single document of a specific data type.
+ *
+ * Each client manages ONE document identified by `dbDocumentId`. Calling `put()`
+ * will overwrite any existing data. For storing multiple items, create separate
+ * clients with different `key` and `dbDocumentId` values.
+ *
+ * All clients share the same underlying Adobe I/O State and Database - they are
+ * lightweight wrappers that provide typed access to specific documents.
+ *
+ * The client provides `put`, `get`, `exists`, and `delete` functions to manage data.
+ *
+ * @example
+ * ```typescript
+ * interface UserPreferences {
+ *   theme: 'light' | 'dark';
+ *   notifications: boolean;
+ * }
+ *
+ * // Each client manages a single document in the shared storage
+ * const prefsClient = createDatabaseStorageClient<UserPreferences>({
+ *   key: 'user-prefs',
+ *   dbCollection: 'preferences',
+ *   dbDocumentId: 'user-prefs',  // Fixed document ID - only one document per client
+ * });
+ *
+ * // Save preferences (overwrites any existing data)
+ * await prefsClient.put({ theme: 'dark', notifications: true });
+ *
+ * // Retrieve preferences
+ * const prefs = await prefsClient.get();
+ * if (prefs) {
+ *   console.log('Theme:', prefs.theme); // Output: "Theme: dark"
+ * }
+ * ```
+ */
+function createDatabaseStorageClient(config) {
+    const fullConfig = {
+        ttl: constants_1.DEFAULT_ONE_YEAR_TTL_SECONDS,
+        ...config,
+    };
+    const encodedKey = (0, utils_1.encodeKey)(fullConfig.key);
+    return {
+        config: fullConfig,
+        /**
+         * Save data to both State (fast access) and Database (permanent backup). The data must be JSON-serializable.
+         */
+        async put(data, logger) {
+            try {
+                const jsonData = JSON.stringify(data);
+                // Initialize both State and Database clients in parallel
+                const [state, db] = await Promise.all([getStateLib(), getDbLib()]);
+                // Connect to database and get the collection
+                const dbClient = await db.connect();
+                const collection = await dbClient.collection(fullConfig.dbCollection);
+                // Prepare the database document (flat structure with _id)
+                const dbDocument = {
+                    _id: fullConfig.dbDocumentId,
+                    ...data,
+                };
+                await collection.replaceOne({ _id: fullConfig.dbDocumentId }, dbDocument, {
+                    upsert: true,
+                });
+                (logger ?? utils_1.defaultLogger).debug(`Data saved to Database (key: ${fullConfig.key})`);
+                // Values exceeding the 1MB State limit are stored in Database only
+                if (Buffer.byteLength(jsonData) > constants_1.MAX_STATE_VALUE_SIZE) {
+                    (logger ?? utils_1.defaultLogger).warn(`Value for key "${fullConfig.key}" exceeds ${constants_1.MAX_STATE_VALUE_SIZE} bytes, storing in Database only`);
+                    return;
+                }
+                await state.put(encodedKey, jsonData, { ttl: fullConfig.ttl });
+                (logger ?? utils_1.defaultLogger).debug(`Data saved to State (key: ${fullConfig.key})`);
+            }
+            catch (error) {
+                (logger ?? utils_1.defaultLogger).error(`Failed to put key: ${fullConfig.key}`, JSON.stringify(error, null, 2));
+                throw error;
+            }
+        },
+        /**
+         * Retrieve data using State-first, Database-fallback strategy. If State has expired, data is restored
+         * from Database automatically (self-healing). `undefined` is returned if no data is found in either State or
+         * Database.
+         */
+        async get(logger) {
+            try {
+                // Try State first (fast path)
+                const state = await getStateLib();
+                const stateResult = await state.get(encodedKey);
+                if (stateResult?.value !== undefined) {
+                    (logger ?? utils_1.defaultLogger).debug(`Data retrieved from State (key: ${fullConfig.key})`);
+                    return JSON.parse(stateResult.value);
+                }
+                // State miss - try Database fallback
+                (logger ?? utils_1.defaultLogger).debug('State miss - trying Database fallback');
+                const db = await getDbLib();
+                const dbClient = await db.connect();
+                const collection = await dbClient.collection(fullConfig.dbCollection);
+                const doc = await collection.findOne({
+                    _id: fullConfig.dbDocumentId,
+                }, { projection: { _id: 0 } } // Exclude _id from the result to get original data shape
+                );
+                // Return `undefined` when document not found (this is expected, not an error)
+                if (doc === null) {
+                    (logger ?? utils_1.defaultLogger).debug('Data not found in State or Database');
+                    return undefined;
+                }
+                // Re-populate State cache if value is within the 1MB size limit
+                const jsonData = JSON.stringify(doc);
+                if (Buffer.byteLength(jsonData) <= constants_1.MAX_STATE_VALUE_SIZE) {
+                    await state.put(encodedKey, jsonData, {
+                        ttl: fullConfig.ttl,
+                    });
+                    // Self-healing: restore to State
+                    (logger ?? utils_1.defaultLogger).debug('Data restored from Database to State (self-healing)');
+                }
+                return doc;
+            }
+            catch (error) {
+                (logger ?? utils_1.defaultLogger).error(`Failed to get key: ${fullConfig.key}`, JSON.stringify(error, null, 2));
+                throw error;
+            }
+        },
+        /**
+         * Check if data exists without returning it.
+         */
+        async exists(logger) {
+            const data = await this.get(logger);
+            return data !== undefined;
+        },
+        /**
+         * Delete data from both State and Database.
+         */
+        async delete(logger) {
+            try {
+                const [state, db] = await Promise.all([getStateLib(), getDbLib()]);
+                const dbClient = await db.connect();
+                const collection = await dbClient.collection(fullConfig.dbCollection);
+                await Promise.all([
+                    state.delete(encodedKey),
+                    collection.deleteOne({ _id: fullConfig.dbDocumentId }),
+                ]);
+                (logger ?? utils_1.defaultLogger).debug(`Data deleted from State (key: ${fullConfig.key}) and Database`);
+            }
+            catch (error) {
+                (logger ?? utils_1.defaultLogger).error(`Failed to delete key: ${fullConfig.key}`, JSON.stringify(error, null, 2));
+                throw error;
+            }
+        },
+    };
+}

package/src/aio-persistent-state/state-files.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @module aio-persistent-state
+ *
+ * A two-tier key-value storage library for Adobe App Builder runtime that
+ * combines Adobe I/O State and Adobe I/O Files to achieve both fast access
+ * and long-term durability.
+ *
+ * **Why both State and Files?**
+ * Adobe I/O State enforces a TTL (Time-To-Live) on all entries, meaning
+ * cached data will expire and be evicted automatically. Files storage has
+ * no such expiration, making it suitable for persistent, long-lived data.
+ * By writing to Files for durability and using State as a fast-access cache,
+ * we get the best of both: speed from State and persistence from Files.
+ *
+ * **1MB size limit:**
+ * Adobe I/O State imposes a maximum value size of 1 MB per entry. Values
+ * that exceed this limit are stored in Files only, bypassing the State
+ * cache entirely. On read, such values are served directly from Files
+ * without being cached in State.
+ */
+import AioLogger from '@adobe/aio-lib-core-logging';
+/**
+ * Configuration options for creating a file storage client.
+ */
+export interface FileStorageClientConfig {
+    /** Key used to identify this data in State and Files storage */
+    key: string;
+    /** TTL (time-to-live) for State storage in seconds. Default: 31536000 (1 year) */
+    ttl?: number;
+}
+/**
+ * Interface for a hybrid State + Files storage client.
+ */
+export interface FileStorageClient {
+    /**
+     * Stores a value, writing through to both State and Files.
+     * Values exceeding 1MB are stored in Files only.
+     */
+    put(value: string, logger?: ReturnType<typeof AioLogger>): Promise<void>;
+    /**
+     * Retrieves a value, using State as a cache layer in front of Files.
+     * Values exceeding 1MB are stored and retrieved from Files only.
+     */
+    get(logger?: ReturnType<typeof AioLogger>): Promise<string | undefined>;
+    /**
+     * Check if data exists without returning it.
+     */
+    exists(logger?: ReturnType<typeof AioLogger>): Promise<boolean>;
+    /**
+     * Delete data from both State and Files.
+     */
+    delete(logger?: ReturnType<typeof AioLogger>): Promise<void>;
+    /** The configuration used to create this client */
+    readonly config: Readonly<Required<FileStorageClientConfig>>;
+}
+/**
+ * Create a hybrid storage client that uses State as a cache and Files as durable storage.
+ *
+ * Each client manages ONE key. Calling `put()` will overwrite any existing data.
+ * For storing multiple items, create separate clients with different `key` values.
+ *
+ * All clients share the same underlying Adobe I/O State and Files instances - they are
+ * lightweight wrappers that provide typed access to specific keys.
+ *
+ * @example
+ * ```typescript
+ * const configClient = createFileStorageClient({ key: 'app-config' });
+ *
+ * // Store a JSON string
+ * await configClient.put(JSON.stringify({ theme: 'dark' }));
+ *
+ * // Retrieve the value
+ * const config = await configClient.get();
+ * if (config) {
+ *   console.log(JSON.parse(config)); // { theme: 'dark' }
+ * }
+ *
+ * // Check existence and delete
+ * if (await configClient.exists()) {
+ *   await configClient.delete();
+ * }
+ * ```
+ */
+export declare function createFileStorageClient(config: FileStorageClientConfig): FileStorageClient;

package/src/aio-persistent-state/state-files.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileStorageClient = createFileStorageClient;
+const aio_lib_files_1 = require("@adobe/aio-lib-files");
+const aio_lib_state_1 = require("@adobe/aio-lib-state");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+let stateLibPromise;
+let filesLibPromise;
+/**
+ * Returns a lazily-initialised Adobe I/O State instance.
+ * The promise is cached so the SDK is only initialised once per process.
+ * If initialisation fails, the cache is cleared so the next call retries.
+ *
+ * @returns A promise that resolves to the Adobe I/O State instance.
+ */
+function getStateLib() {
+    stateLibPromise ??= (0, aio_lib_state_1.init)().catch(err => {
+        stateLibPromise = undefined;
+        throw err;
+    });
+    return stateLibPromise;
+}
+/**
+ * Returns a lazily-initialised Adobe I/O Files instance.
+ * The promise is cached so the SDK is only initialised once per process.
+ * If initialisation fails, the cache is cleared so the next call retries.
+ *
+ * @returns A promise that resolves to the Adobe I/O Files instance.
+ */
+function getFilesLib() {
+    filesLibPromise ??= (0, aio_lib_files_1.init)().catch(err => {
+        filesLibPromise = undefined;
+        throw err;
+    });
+    return filesLibPromise;
+}
+/**
+ * Create a hybrid storage client that uses State as a cache and Files as durable storage.
+ *
+ * Each client manages ONE key. Calling `put()` will overwrite any existing data.
+ * For storing multiple items, create separate clients with different `key` values.
+ *
+ * All clients share the same underlying Adobe I/O State and Files instances - they are
+ * lightweight wrappers that provide typed access to specific keys.
+ *
+ * @example
+ * ```typescript
+ * const configClient = createFileStorageClient({ key: 'app-config' });
+ *
+ * // Store a JSON string
+ * await configClient.put(JSON.stringify({ theme: 'dark' }));
+ *
+ * // Retrieve the value
+ * const config = await configClient.get();
+ * if (config) {
+ *   console.log(JSON.parse(config)); // { theme: 'dark' }
+ * }
+ *
+ * // Check existence and delete
+ * if (await configClient.exists()) {
+ *   await configClient.delete();
+ * }
+ * ```
+ */
+function createFileStorageClient(config) {
+    const fullConfig = {
+        ttl: constants_1.DEFAULT_ONE_YEAR_TTL_SECONDS,
+        ...config,
+    };
+    const encodedKey = (0, utils_1.encodeKey)(fullConfig.key);
+    const filePath = `${fullConfig.key}.json`;
+    return {
+        config: fullConfig,
+        /**
+         * Retrieves a value by key, using State as a cache layer in front of Files.
+         *
+         * 1. Attempts to read from State (fast, but subject to TTL expiry).
+         * 2. On a cache miss, falls back to Files (persistent, no TTL).
+         * 3. If the value from Files is within the 1 MB State limit, it is
+         *    written back into State so subsequent reads are served from cache.
+         *
+         * @returns The stored string value, or `undefined` if not found.
+         * @throws {Error} If a storage operation fails (other than "not found").
+         */
+        async get(logger) {
+            try {
+                const stateLib = await getStateLib();
+                // Try to retrieve from State cache (may be missing due to TTL expiry)
+                const cache = await stateLib.get(encodedKey);
+                if (cache?.value !== undefined) {
+                    (logger ?? utils_1.defaultLogger).debug(`Data retrieved from State (key: ${fullConfig.key})`);
+                    return cache.value;
+                }
+                // Fallback: read from Files (persistent, no TTL)
+                (logger ?? utils_1.defaultLogger).debug('State miss - trying Files fallback');
+                const filesLib = await getFilesLib();
+                const buffer = await filesLib.read(filePath);
+                const value = buffer.toString();
+                // Re-populate State cache if value is within the 1MB size limit
+                if (Buffer.byteLength(value) <= constants_1.MAX_STATE_VALUE_SIZE) {
+                    await stateLib.put(encodedKey, value, { ttl: fullConfig.ttl });
+                    // Self-healing: restore to State
+                    (logger ?? utils_1.defaultLogger).debug('Data restored from Files to State (self-healing)');
+                }
+                return value;
+            }
+            catch (error) {
+                (logger ?? utils_1.defaultLogger).error(`Failed to get key: ${fullConfig.key}`, JSON.stringify(error, null, 2));
+                // Return `undefined` when data is not found and throw other errors
+                if (error instanceof Error &&
+                    'code' in error &&
+                    error.code === 'ERROR_FILE_NOT_EXISTS') {
+                    return undefined;
+                }
+                throw error;
+            }
+        },
+        /**
+         * Stores a value by key, writing through to both Files and State.
+         *
+         * 1. Always writes to Files first to guarantee durability (no TTL).
+         * 2. If the value is within the 1 MB State limit, it is also written to
+         *    State for fast subsequent reads.
+         * 3. Values exceeding 1 MB are stored in Files only; State is skipped
+         *    because it cannot hold entries larger than 1 MB.
+         *
+         * @param value - The string value to store.
+         * @throws {Error} If the encoded key exceeds the maximum size or a
+         *   storage operation fails.
+         */
+        async put(value, logger) {
+            try {
+                const filesLib = await getFilesLib();
+                // Always write to Files first for durability (no TTL)
+                await filesLib.write(filePath, value);
+                (logger ?? utils_1.defaultLogger).debug(`Data saved to File (file path: ${filePath})`);
+                // Values exceeding the 1MB State limit are stored in Files only
+                if (Buffer.byteLength(value) > constants_1.MAX_STATE_VALUE_SIZE) {
+                    (logger ?? utils_1.defaultLogger).warn(`Value for key "${fullConfig.key}" exceeds ${constants_1.MAX_STATE_VALUE_SIZE} bytes, storing in file only`);
+                    return;
+                }
+                // Also cache in State for fast access (subject to TTL expiry)
+                const stateLib = await getStateLib();
+                await stateLib.put(encodedKey, value, {
+                    ttl: fullConfig.ttl,
+                });
+                (logger ?? utils_1.defaultLogger).debug(`Data saved to State (key: ${fullConfig.key})`);
+                return;
+            }
+            catch (error) {
+                (logger ?? utils_1.defaultLogger).error(`Failed to put key: ${fullConfig.key}`, JSON.stringify(error, null, 2));
+                throw error;
+            }
+        },
+        /**
+         * Check if data exists without returning it.
+         *
+         * Returns `true` if data is found in either State or Files storage,
+         * even if the stored value is an empty string. Returns `false` only
+         * when the underlying file does not exist (i.e., `get()` returns `undefined`).
+         *
+         * @returns `true` if data exists (including empty strings), `false` if not found.
+         */
+        async exists(logger) {
+            const value = await this.get(logger);
+            return value !== undefined;
+        },
+        /**
+         * Delete data from both State and Files.
+         */
+        async delete(logger) {
+            try {
+                const [stateLib, filesLib] = await Promise.all([getStateLib(), getFilesLib()]);
+                await Promise.all([stateLib.delete(encodedKey), filesLib.delete(filePath)]);
+                (logger ?? utils_1.defaultLogger).debug(`Data deleted from State (key: ${fullConfig.key}) and File`);
+            }
+            catch (error) {
+                (logger ?? utils_1.defaultLogger).error(`Failed to delete key: ${fullConfig.key}`, JSON.stringify(error, null, 2));
+                throw error;
+            }
+        },
+    };
+}

package/src/aio-persistent-state/utils.d.ts

@@ -0,0 +1,25 @@
+/** Default logger instance for the aio-persistent-state module. */
+export declare const defaultLogger: {
+    LogProvider: typeof import("@adobe/aio-lib-core-logging/types/WinstonLogger") | typeof import("@adobe/aio-lib-core-logging/types/DebugLogger");
+    logger: import("@adobe/aio-lib-core-logging/types/WinstonLogger") | import("@adobe/aio-lib-core-logging/types/DebugLogger");
+    setDefaults(moduleName: any, config: any): void;
+    config: {};
+    generateLabel(moduleName: any, config: any): string;
+    close(): void;
+    error(...data?: (object | string)[]): void;
+    warn(...data?: (object | string)[]): void;
+    info(...data?: (object | string)[]): void;
+    log(...data?: (object | string)[]): void;
+    verbose(...data?: (object | string)[]): void;
+    debug(...data?: (object | string)[]): void;
+    silly(...data?: (object | string)[]): void;
+};
+/**
+ * Encodes a key using base64url so it is safe for use in Adobe I/O State,
+ * which requires keys to match the pattern `/^[a-zA-Z0-9-_.]{1,1024}$/`.
+ *
+ * @param key - The original key string.
+ * @returns The base64url-encoded key.
+ * @throws {Error} If the encoded key exceeds 1024 characters ({@link MAX_KEY_SIZE}).
+ */
+export declare function encodeKey(key: string): string;

package/src/aio-persistent-state/utils.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLogger = void 0;
+exports.encodeKey = encodeKey;
+const aio_lib_core_logging_1 = __importDefault(require("@adobe/aio-lib-core-logging"));
+const base64url_1 = __importDefault(require("base64url"));
+const constants_1 = require("./constants");
+/** Default logger instance for the aio-persistent-state module. */
+exports.defaultLogger = (0, aio_lib_core_logging_1.default)('aio-persistent-state', {
+    level: 'info',
+});
+/**
+ * Encodes a key using base64url so it is safe for use in Adobe I/O State,
+ * which requires keys to match the pattern `/^[a-zA-Z0-9-_.]{1,1024}$/`.
+ *
+ * @param key - The original key string.
+ * @returns The base64url-encoded key.
+ * @throws {Error} If the encoded key exceeds 1024 characters ({@link MAX_KEY_SIZE}).
+ */
+function encodeKey(key) {
+    const encodedKey = base64url_1.default.encode(key);
+    if (encodedKey.length > constants_1.MAX_KEY_SIZE) {
+        throw new Error(`Encoded key exceeds maximum size of ${constants_1.MAX_KEY_SIZE} characters`);
+    }
+    return encodedKey;
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Main entry point for @aligent/appbuilder-util-lib
+ */
+export * as PersistentState from './aio-persistent-state';

package/src/index.js

@@ -37,5 +37,4 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PersistentState = void 0;
-const PersistentState = __importStar(require("./aio-persistent-state/aio-persistent-state"));
-exports.PersistentState = PersistentState;
+exports.PersistentState = __importStar(require("./aio-persistent-state"));

package/tsconfig.lib.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.9.3"}

package/docs/functions/get.md

@@ -1,42 +0,0 @@
-[**@aligent/appbuilder-util-lib**](../modules.md)
-
-***
-
-[@aligent/appbuilder-util-lib](../modules.md) / [aio-persistent-state](../modules/aio-persistent-state.md) / PersistentState.get
-
-# Function: PersistentState.get()
-
-> **get**(`key`): `Promise`\<`string`\>
-
-Retrieves a value by key, using State as a cache layer in front of Files.
-
-1. Attempts to read from State (fast, but subject to TTL expiry).
-2. On a cache miss, falls back to Files (persistent, no TTL).
-3. If the value from Files is within the 1 MB State limit, it is
-   written back into State so subsequent reads are served from cache.
-
-## Parameters
-
-### key
-
-`string`
-
-The key to look up.
-
-## Returns
-
-`Promise`\<`string`\>
-
-The stored string value.
-
-## Throws
-
-If the encoded key exceeds the maximum size or both storage layers fail.
-
-## Example
-
-```ts
-import { PersistentState } from '@aligent/appbuilder-util-lib';
-
-const value = await PersistentState.get('myKey');
-```

package/docs/functions/put.md

@@ -1,49 +0,0 @@
-[**@aligent/appbuilder-util-lib**](../modules.md)
-
-***
-
-[@aligent/appbuilder-util-lib](../modules.md) / [aio-persistent-state](../modules/aio-persistent-state.md) / PersistentState.put
-
-# Function: PersistentState.put()
-
-> **put**(`key`, `value`): `Promise`\<`string`\>
-
-Stores a value by key, writing through to both Files and State.
-
-1. Always writes to Files first to guarantee durability (no TTL).
-2. If the value is within the 1 MB State limit, it is also written to
-   State for fast subsequent reads.
-3. Values exceeding 1 MB are stored in Files only; State is skipped
-   because it cannot hold entries larger than 1 MB.
-
-## Parameters
-
-### key
-
-`string`
-
-The key under which to store the value.
-
-### value
-
-`string`
-
-The string value to store.
-
-## Returns
-
-`Promise`\<`string`\>
-
-The base64url-encoded key.
-
-## Throws
-
-If the encoded key exceeds the maximum size or a storage operation fails.
-
-## Example
-
-```ts
-import { PersistentState } from '@aligent/appbuilder-util-lib';
-
-const encodedKey = await PersistentState.put('myKey', 'myValue');
-```

package/src/aio-persistent-state/aio-persistent-state.js

@@ -1,151 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.get = get;
-exports.put = put;
-/**
- * @module aio-persistent-state
- *
- * A two-tier key-value storage library for Adobe App Builder runtime that
- * combines Adobe I/O State and Adobe I/O Files to achieve both fast access
- * and long-term durability.
- *
- * **Why both State and Files?**
- * Adobe I/O State enforces a TTL (Time-To-Live) on all entries, meaning
- * cached data will expire and be evicted automatically. Files storage has
- * no such expiration, making it suitable for persistent, long-lived data.
- * By writing to Files for durability and using State as a fast-access cache,
- * we get the best of both: speed from State and persistence from Files.
- *
- * **1MB size limit:**
- * Adobe I/O State imposes a maximum value size of 1 MB per entry. Values
- * that exceed this limit are stored in Files only, bypassing the State
- * cache entirely. On read, such values are served directly from Files
- * without being cached in State.
- */
-const aio_sdk_1 = require("@adobe/aio-sdk");
-const base64url_1 = __importDefault(require("base64url"));
-const logger = aio_sdk_1.Core.Logger('aio-persistent-state', { level: 'info' });
-let stateLibPromise;
-let filesLibPromise;
-/**
- * Returns a lazily-initialised Adobe I/O State instance.
- * The promise is cached so the SDK is only initialised once per process.
- * If initialisation fails, the cache is cleared so the next call retries.
- *
- * @returns A promise that resolves to the Adobe I/O State instance.
- */
-function getStateLib() {
-    stateLibPromise ??= aio_sdk_1.State.init().catch(err => {
-        stateLibPromise = undefined;
-        throw err;
-    });
-    return stateLibPromise;
-}
-/**
- * Returns a lazily-initialised Adobe I/O Files instance.
- * The promise is cached so the SDK is only initialised once per process.
- * If initialisation fails, the cache is cleared so the next call retries.
- *
- * @returns A promise that resolves to the Adobe I/O Files instance.
- */
-function getFilesLib() {
-    filesLibPromise ??= aio_sdk_1.File.init().catch(err => {
-        filesLibPromise = undefined;
-        throw err;
-    });
-    return filesLibPromise;
-}
-/** Maximum length (in characters) of a base64url-encoded key accepted by State. */
-const MAX_KEY_SIZE = 1024;
-/** Maximum value size (in bytes) accepted by Adobe I/O State (1 MB). */
-const MAX_VALUE_SIZE = 1024 * 1024; // 1MB
-/**
- * Encodes a key using base64url so it is safe for use in Adobe I/O State,
- * which requires keys to match the pattern `/^[a-zA-Z0-9-_.]{1,1024}$/`.
- *
- * @param key - The original key string.
- * @returns The base64url-encoded key.
- * @throws {Error} If the encoded key exceeds 1024 characters ({@link MAX_KEY_SIZE}).
- */
-function encodeKey(key) {
-    const encodedKey = base64url_1.default.encode(key);
-    if (encodedKey.length > MAX_KEY_SIZE) {
-        throw new Error(`Encoded key exceeds maximum size of ${MAX_KEY_SIZE} characters`);
-    }
-    return encodedKey;
-}
-/**
- * Retrieves a value by key, using State as a cache layer in front of Files.
- *
- * 1. Attempts to read from State (fast, but subject to TTL expiry).
- * 2. On a cache miss, falls back to Files (persistent, no TTL).
- * 3. If the value from Files is within the 1 MB State limit, it is
- *    written back into State so subsequent reads are served from cache.
- *
- * @param key - The key to look up.
- * @returns The stored string value.
- * @throws {Error} If the encoded key exceeds the maximum size or both
- *   storage layers fail.
- */
-async function get(key) {
-    try {
-        const stateLib = await getStateLib();
-        const encodedKey = encodeKey(key);
-        // Try to retrieve from State cache (may be missing due to TTL expiry)
-        const cache = await stateLib.get(encodedKey);
-        if (cache?.value != null) {
-            return cache.value;
-        }
-        // Fallback: read from Files (persistent, no TTL)
-        const filesLib = await getFilesLib();
-        const buffer = await filesLib.read(`${key}.json`);
-        const value = buffer.toString();
-        // Re-populate State cache if value is within the 1MB size limit
-        if (Buffer.byteLength(value) <= MAX_VALUE_SIZE) {
-            await stateLib.put(encodedKey, value);
-        }
-        return value;
-    }
-    catch (error) {
-        logger.error(`Failed to get key: ${key}`, JSON.stringify(error, null, 2));
-        throw error;
-    }
-}
-/**
- * Stores a value by key, writing through to both Files and State.
- *
- * 1. Always writes to Files first to guarantee durability (no TTL).
- * 2. If the value is within the 1 MB State limit, it is also written to
- *    State for fast subsequent reads.
- * 3. Values exceeding 1 MB are stored in Files only; State is skipped
- *    because it cannot hold entries larger than 1 MB.
- *
- * @param key - The key under which to store the value.
- * @param value - The string value to store.
- * @returns The base64url-encoded key.
- * @throws {Error} If the encoded key exceeds the maximum size or a
- *   storage operation fails.
- */
-async function put(key, value) {
-    try {
-        const encodedKey = encodeKey(key);
-        const filesLib = await getFilesLib();
-        // Always write to Files first for durability (no TTL)
-        await filesLib.write(`${key}.json`, value);
-        // Values exceeding the 1MB State limit are stored in Files only
-        if (Buffer.byteLength(value) > MAX_VALUE_SIZE) {
-            logger.warn(`Value for key "${key}" exceeds ${MAX_VALUE_SIZE} bytes, storing in file only`);
-            return encodedKey;
-        }
-        // Also cache in State for fast access (subject to TTL expiry)
-        const stateLib = await getStateLib();
-        return await stateLib.put(encodedKey, value);
-    }
-    catch (error) {
-        logger.error(`Failed to put key: ${key}`, JSON.stringify(error, null, 2));
-        throw error;
-    }
-}