@aligent/appbuilder-util-lib 0.2.0

package/README.md

@@ -0,0 +1,31 @@
+# App Builder Utilities Library
+
+This library includes utility functions to simplify & standardise common
+Adobe App Builder tasks.
+
+## Documentation
+
+Documentation on each function can be found [here](docs/modules.md)
+
+## Build
+
+This library is written in typescript and can be built using:
+
+```sh
+npx nx build appbuilder-util-lib
+```
+
+## Installation
+
+```sh
+npm install @aligent/appbuilder-util-lib
+```
+
+## Testing & Linting
+
+Vitest tests, linting & type-checking can be run with
+
+```sh
+npx nx test appbuilder-util-lib
+npx nx lint appbuilder-util-lib
+```

package/docs/functions/get.md

@@ -0,0 +1,42 @@
+[**@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

@@ -0,0 +1,49 @@
+[**@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/docs/modules/aio-persistent-state.md

@@ -0,0 +1,39 @@
+[**@aligent/appbuilder-util-lib**](../modules.md)
+
+***
+
+[@aligent/appbuilder-util-lib](../modules.md) / aio-persistent-state
+
+# 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).
+
+## 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
+
+### Why both State and Files?
+
+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.
+
+### 1 MB State size limit
+
+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.
+
+Values within the 1 MB limit are stored in both layers so that subsequent reads are served from the faster State cache.
+
+### How it works
+
+- 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
+
+## Functions
+
+- [PersistentState.get](../functions/get.md)
+- [PersistentState.put](../functions/put.md)

package/docs/modules.md

@@ -0,0 +1,9 @@
+**@aligent/appbuilder-util-lib**
+
+***
+
+# @aligent/appbuilder-util-lib
+
+## Modules
+
+- [aio-persistent-state](modules/aio-persistent-state.md)

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@aligent/appbuilder-util-lib",
+  "version": "0.2.0",
+  "description": "A utility library to simplify and standardise common Adobe App Builder tasks.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aligent/microservice-development-utilities.git",
+    "directory": "packages/appbuilder-util-lib"
+  },
+  "dependencies": {
+    "@adobe/aio-sdk": "^6.0.0",
+    "base64url": "^3.0.1"
+  },
+  "author": "Aligent",
+  "license": "MIT",
+  "types": "./src/index.d.ts"
+}

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

@@ -0,0 +1,151 @@
+"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;
+    }
+}

package/src/index.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Main entry point for @aligent/appbuilder-util-lib
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistentState = void 0;
+const PersistentState = __importStar(require("./aio-persistent-state/aio-persistent-state"));
+exports.PersistentState = PersistentState;