@asaidimu/utils-artifacts 8.2.6 → 8.2.8

package/README.md

@@ -224,6 +224,162 @@ observer.subscribe((resolved) => {
 });
 ```
 
+### Persistence: Export and Import
+
+The container can export its current set of built singleton artifacts into a serializable bundle and later restore them in a new container. This is useful for **saving/reloading application state**, or **transferring** a snapshot across environments.
+
+#### Exporting Artifacts
+
+Call `container.export()` to generate a JSON‑compatible bundle.
+
+- The method **waits** for all currently resolving artifacts to finish.
+- Only **singleton** artifacts that have been fully built (i.e., `ready === true`) are included.
+- Each exported artifact stores:
+  - Its resolved `instance` (must be JSON‑serializable).
+  - The **state groups** (store selectors) it depends on, with their paths and options.
+  - Its list of **artifact dependencies** (other artifact keys).
+- The bundle contains a **checksum** to detect corruption.
+
+```typescript
+const bundle = await container.export();
+// {
+//   version: "1.0",
+//   timestamp: 1700000000000,
+//   checksum: "abc123...",
+//   artifacts: [
+//     {
+//       key: "config",
+//       instance: { theme: "dark" },
+//       state: { groups: [{ paths: ["theme"], options: undefined }] },
+//       dependencies: []
+//     },
+//     // ...
+//   ]
+// }
+```
+
+> **Note**: Transient artifacts are **never** exported. If an artifact instance contains non‑serializable values (e.g., functions, symbols), `export()` will throw an error.
+
+#### Importing Artifacts
+
+Use the static `ArtifactContainer.from()` method to create a new container pre‑filled with exported data.
+
+- You must provide:
+  - A `store` (the same or a different `ReactiveDataStore`).
+  - The previously exported `bundle`.
+  - The **original artifact templates** (the container does not store factory functions).
+- The method validates the bundle’s checksum. On mismatch, it throws `"Bundle checksum mismatch"`.
+- For each exported artifact, the container **restores the instance only if** all its state groups still match the current store’s data. If any selected slice has changed, the artifact is marked **stale** (not restored) and will be rebuilt on the next `resolve()`.
+
+```typescript
+// Create a new container from a bundle
+const restoredContainer = await ArtifactContainer.from({
+  store: new ReactiveDataStore(initialState),
+  bundle: savedBundle,
+  templates: [
+    {
+      key: "config",
+      factory: async ({ use }) => ({
+        theme: await use(({ select }) => select((s: any) => s.theme)),
+      }),
+      scope: "singleton",
+    },
+    {
+      key: "userName",
+      factory: async ({ use }) =>
+        `User-${await use(({ select }) => select((s: any) => s.userId))}`,
+      scope: "singleton",
+    },
+    // ... other templates
+  ],
+});
+```
+
+#### Staleness and Reactivity
+
+When importing, the container compares the exported **state groups** (store selectors) with the **current store**:
+
+- If **all** state group values are identical → the artifact instance is restored directly (no rebuild).
+- If **any** value differs → the artifact is **skipped** (not restored) and its cache entry remains empty. The next `resolve()` will run the factory again, using the latest store data.
+
+Staleness **propagates** through the dependency graph: if artifact `A` depends on `B` and `B` is stale, then `A` is also considered stale and will be rebuilt.
+
+```typescript
+// Example: store changed from { theme: "dark", userId: 42 } to { theme: "light", userId: 42 }
+// - config (depends on theme) → stale, not restored
+// - userName (depends on userId) → fresh, restored
+// - greeting (depends on config) → stale (transitive), not restored
+```
+
+#### Parameterized Artifacts
+
+Parameterized singletons are exported and imported **per parameter key**. The same staleness checks apply independently for each parameter combination.
+
+```typescript
+container.register({
+  key: "user",
+  paramKey: (params) => `user:${params.userId}`,
+  factory: async (ctx) => ({ id: ctx.params.userId, name: "..." }),
+  scope: "singleton",
+});
+
+// Export includes both user:alice and user:bob
+const bundle = await container.export();
+
+// Later, restore both instances
+const newContainer = await ArtifactContainer.from({ store, bundle, templates });
+newContainer.peek("user", { userId: "alice" }); // restored instance
+newContainer.peek("user", { userId: "bob" }); // restored instance
+```
+
+#### Complete Example
+
+```typescript
+import { ReactiveDataStore } from "@asaidimu/utils-store";
+import { ArtifactContainer } from "@asaidimu/utils-artifacts";
+
+// 1. Initial setup
+const store = new ReactiveDataStore({ theme: "dark", userId: 42 });
+const container = new ArtifactContainer(store);
+
+container.register({
+  key: "greeting",
+  factory: async ({ use }) => {
+    const theme = await use(({ select }) => select((s: any) => s.theme));
+    const userId = await use(({ select }) => select((s: any) => s.userId));
+    return `${theme} greeting for user ${userId}`;
+  },
+  scope: "singleton",
+  lazy: false,
+});
+
+await container.resolve("greeting"); // builds "dark greeting for user 42"
+
+// 2. Export the bundle
+const bundle = await container.export();
+
+// 3. Later, in a different environment (e.g., another request)
+const newStore = new ReactiveDataStore({ theme: "light", userId: 42 });
+const restored = await ArtifactContainer.from({
+  store: newStore,
+  bundle,
+  templates: [
+    /* same greeting template */
+  ],
+});
+
+// theme changed → greeting is stale, will be rebuilt on demand
+const greeting = await restored.require("greeting");
+console.log(greeting); // "light greeting for user 42"
+```
+
+#### Important Notes
+
+- The exported bundle is **read‑only** and should be treated as an immutable snapshot.
+- Always provide **all necessary templates** when calling `from()`. Missing templates cause resolution errors.
+- For high‑cardinality parameterized artifacts, consider cleaning up unused keys before exporting to keep the bundle size reasonable.
+- The checksum prevents accidental corruption but does **not** provide cryptographic security.
+
 ## 5. Architecture
 
 `@asaidimu/utils-artifacts` implements a **Directed Acyclic Graph (DAG)** for dependency management using a **Pull-based Invalidation** model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-artifacts",
-  "version": "8.2.6",
+  "version": "8.2.8",
   "description": "Reactive artifact container.",
   "main": "index.js",
   "module": "index.mjs",