libmodulor 0.18.1 → 0.20.0

package/dist/esm/uc/impl/CloudflareD1UCDataStore.js

@@ -0,0 +1,201 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'inversify';
+import { NotAvailableError, NotImplementedError } from '../../error/index.js';
+export const ROW_COLS = [
+    'aggregateId',
+    'appName',
+    'createdAt',
+    'data',
+    'executionMode',
+    'id',
+    'input',
+    'name',
+    'organizationId',
+    'userId',
+];
+/**
+ * @alpha This implementation is still a WIP and needs improvement
+ */
+let CloudflareD1UCDataStore = class CloudflareD1UCDataStore {
+    settingsManager;
+    // Defined as protected and not private so the `assertClient` guard works correctly
+    // See https://stackoverflow.com/a/74267363/1259118
+    // > Such property type guards only work when the property you are narrowing is not private; if the property is private then this gets narrowed to never because an object with a private property is not assignable to an object with a public property of the same key.
+    client;
+    constructor(settingsManager) {
+        this.settingsManager = settingsManager;
+    }
+    s() {
+        return {
+            uc_data_store_ucs_dataset_name: this.settingsManager.get()('uc_data_store_ucs_dataset_name'),
+        };
+    }
+    async clear() {
+        throw new NotImplementedError('clear');
+    }
+    async destroy() {
+        throw new NotImplementedError('destroy');
+    }
+    async exists() {
+        throw new NotImplementedError('exists');
+    }
+    async init() {
+        throw new NotAvailableError('initSync');
+        // Since workers do not accept top-level await, we cannot invoke this method when initiating it.
+        // Plus, calling it in every request handler would be overkill and would add too much overhead.
+        // In the meantime, process as follows :
+        /*
+            mkdir path_to_target/migrations
+
+            cat > path_to_target/migrations/001_init.sql <<'EOF'
+-- Table Definition
+CREATE TABLE IF NOT EXISTS uc_executions (
+    "aggregateId" uuid NOT NULL,
+    "appName" varchar(255) NOT NULL,
+    "createdAt" timestamptz NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "data" jsonb,
+    "executionMode" varchar(255) NOT NULL,
+    "id" uuid NOT NULL,
+    "input" jsonb,
+    "name" varchar(255) NOT NULL,
+    "organizationId" uuid,
+    "userId" uuid,
+    PRIMARY KEY ("id")
+);
+
+-- Indices
+CREATE INDEX IF NOT EXISTS uc_executions_aggregate_id_index ON uc_executions (aggregateId);
+CREATE INDEX IF NOT EXISTS uc_executions_name_index ON uc_executions (name);
+CREATE INDEX IF NOT EXISTS uc_executions_organization_id_index ON uc_executions (organizationId);
+CREATE INDEX IF NOT EXISTS uc_executions_user_id_index ON uc_executions (userId);
+            EOF
+
+            pnpm wrangler d1 create my-app-uc-data-store
+            pnpm wrangler d1 execute my-app-uc-data-store --cwd path_to_target --local --file=./migrations/001_init.sql
+            pnpm wrangler d1 execute my-app-uc-data-store --cwd path_to_target --remote --file=./migrations/001_init.sql
+            pnpm wrangler d1 list
+        */
+    }
+    initSync() {
+        throw new NotAvailableError('initSync');
+    }
+    async read(opts) {
+        this.assertClient();
+        // TODO : Consider using a query builder (or Google's pipe operator ?) when it gets too complicated or dangerous
+        const query = [
+            `select * from ${this.s().uc_data_store_ucs_dataset_name}`,
+        ];
+        // Filter
+        const where = [];
+        const bindings = [];
+        if (opts?.filters) {
+            const { aggregateId, appName, idWithinInput, name, organizationId, userId, } = opts.filters;
+            this.filter(where, bindings, aggregateId, 'aggregateId');
+            this.filter(where, bindings, appName, 'appName');
+            this.filter(where, bindings, name, 'name');
+            this.filter(where, bindings, organizationId, 'organizationId');
+            this.filter(where, bindings, userId, 'userId');
+            if (idWithinInput !== undefined) {
+                // TODO : Implement CloudflareD1UCDataStore.read.opts.filters.idWithinInput
+                throw new Error('opts.filters.idWithinInput is not supported yet');
+            }
+        }
+        if (where.length > 0) {
+            query.push('where', where.join(' and '));
+        }
+        // Sort
+        query.push('order by createdAt asc');
+        const sql = query.join(' ');
+        const { results } = await this.client
+            .prepare(sql)
+            .bind(...bindings)
+            .run();
+        const records = results.map((r) => ({
+            ...r,
+            data: JSON.parse(r.data),
+            input: JSON.parse(r.input),
+        }));
+        return {
+            records,
+        };
+    }
+    async readProjection(_name, _opts) {
+        throw new NotImplementedError('readProjection');
+    }
+    async startTx() {
+        throw new NotImplementedError('startTx');
+    }
+    supportedSpecificBindings() {
+        throw new NotImplementedError('supportedSpecificBindings');
+    }
+    async testKey(_encryptionKey) {
+        throw new NotAvailableError('testKey');
+    }
+    async write(record, _opts) {
+        this.assertClient();
+        const cols = ROW_COLS.join(', ');
+        const placeholders = ROW_COLS.map(() => '?').join(', ');
+        // Use variables only for variables declared here => never for data coming from outside this method !
+        const query = `insert into ${this.s().uc_data_store_ucs_dataset_name} (${cols}) values (${placeholders})`;
+        const values = ROW_COLS.map((c) => {
+            const val = record[c];
+            if (val instanceof Date) {
+                // D1_TYPE_ERROR: Type 'object' not supported for value 'Wed Jun 18 2025 13:32:27 GMT+0200 (Central European Summer Time)
+                return val.toISOString();
+            }
+            if (val !== null && typeof val === 'object') {
+                // D1_TYPE_ERROR: Type 'object' not supported for value '[object Object]'
+                return JSON.stringify(val);
+            }
+            return val;
+        });
+        await this.client
+            .prepare(query)
+            .bind(...values)
+            .run();
+    }
+    async writeBulk(_records, _opts) {
+        throw new NotImplementedError('writeBulk');
+    }
+    async writeProjection(_name, _data, _opts) {
+        throw new NotImplementedError('writeProjection');
+    }
+    setClient(client) {
+        this.client = client;
+    }
+    assertClient() {
+        if (this.client === undefined) {
+            throw new Error('You must call UCDataStore#setClient with the D1Database from the context (e.g. hono context)');
+        }
+    }
+    filter(query, bindings, value, field) {
+        if (value === undefined) {
+            return;
+        }
+        if (Array.isArray(value)) {
+            query.push(`${field} in (${value.map(() => '?')})`);
+            bindings.push(...value);
+        }
+        else {
+            query.push(`${field} = ?`);
+            bindings.push(value);
+        }
+    }
+};
+CloudflareD1UCDataStore = __decorate([
+    injectable(),
+    __param(0, inject('SettingsManager')),
+    __metadata("design:paramtypes", [Object])
+], CloudflareD1UCDataStore);
+export { CloudflareD1UCDataStore };

package/dist/esm/uc/impl/InMemoryUCDataStore.d.ts

@@ -9,10 +9,11 @@ export declare class InMemoryUCDataStore implements UCDataStore {
     clear(): Promise<void>;
     destroy(): Promise<void>;
     exists(): Promise<boolean>;
-    initTx(): Promise<UCDataStoreTx['ref']>;
-    install(): Promise<void>;
+    init(): Promise<void>;
+    initSync(): void;
     read<I extends UCInput | undefined = undefined, D extends UCData | null = null>(opts?: UCDataStoreReadOpts<I, D>): Promise<UCDataStoreReadResponse<I, D>>;
     readProjection<T extends object>(): Promise<T[]>;
+    startTx(): Promise<UCDataStoreTx['ref']>;
     supportedSpecificBindings(): UCDataStoreWriteProjectionSpecificBinding[];
     testKey(): Promise<void>;
     write<I extends UCInput | undefined = undefined, D extends UCData | null = null>(record: UCDataStoreRecord<I, D>): Promise<void>;

package/dist/esm/uc/impl/InMemoryUCDataStore.js

@@ -8,7 +8,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 import { injectable } from 'inversify';
-const ERR = 'Method not implemented.';
+import { NotImplementedError } from '../../error/index.js';
 function predicate(key, filter) {
     if (filter === null) {
         return (r) => r[key] === null;
@@ -34,19 +34,10 @@ let InMemoryUCDataStore = class InMemoryUCDataStore {
     async exists() {
         return this.entries.length > 0;
     }
-    async initTx() {
-        this.tx = 'pending';
-        return {
-            commit: async () => {
-                this.tx = 'committed';
-            },
-            rollback: async () => {
-                this.tx = 'rollbacked';
-                this.entries = [];
-            },
-        };
+    async init() {
+        // Nothing to do
     }
-    async install() {
+    initSync() {
         // Nothing to do
     }
     async read(opts) {
@@ -81,6 +72,18 @@ let InMemoryUCDataStore = class InMemoryUCDataStore {
     async readProjection() {
         return [];
     }
+    async startTx() {
+        this.tx = 'pending';
+        return {
+            commit: async () => {
+                this.tx = 'committed';
+            },
+            rollback: async () => {
+                this.tx = 'rollbacked';
+                this.entries = [];
+            },
+        };
+    }
     supportedSpecificBindings() {
         return [];
     }
@@ -94,7 +97,7 @@ let InMemoryUCDataStore = class InMemoryUCDataStore {
         this.entries.push(...records);
     }
     async writeProjection() {
-        throw new Error(ERR);
+        throw new NotImplementedError('writeProjection');
     }
 };
 InMemoryUCDataStore = __decorate([

package/dist/esm/uc/impl/KnexUCDataStore.d.ts

@@ -26,10 +26,11 @@ export declare class KnexUCDataStore implements Configurable<S>, UCDataStore {
     clear(): Promise<void>;
     destroy(): Promise<void>;
     exists(): Promise<boolean>;
-    initTx(): Promise<UCDataStoreTx['ref']>;
-    install(): Promise<void>;
+    init(): Promise<void>;
+    initSync(): void;
     read<I extends UCInput | undefined = undefined, D extends UCData | null = null>(opts?: UCDataStoreReadOpts<I, D>): Promise<UCDataStoreReadResponse<I, D>>;
     readProjection<T extends object>(name: string, opts?: UCDataStoreReadProjectionOpts<T>): Promise<T[]>;
+    startTx(): Promise<UCDataStoreTx['ref']>;
     supportedSpecificBindings(): UCDataStoreWriteProjectionSpecificBinding[];
     testKey(_encryptionKey: Uint8Array): Promise<void>;
     write<I extends UCInput | undefined = undefined, D extends UCData | null = null>(record: UCDataStoreRecord<I, D>, opts?: UCDataStoreWriteOpts): Promise<void>;

package/dist/esm/uc/impl/KnexUCDataStore.js

@@ -12,6 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from 'inversify';
 import knex, {} from 'knex';
+import { NotAvailableError, NotCallableError } from '../../error/index.js';
 const FILTERS_MAPPING = new Map([
     ['aggregateId', 'aggregate_id'],
     ['appName', 'app_name'],
@@ -50,12 +51,12 @@ let KnexUCDataStore = class KnexUCDataStore {
     async exists() {
         return this.client.schema.hasTable(this.s().uc_data_store_ucs_dataset_name);
     }
-    async initTx() {
-        return this.client.transaction();
-    }
-    async install() {
+    async init() {
         await this.migration001CreateMainTable();
     }
+    initSync() {
+        throw new NotCallableError('initSync', 'init', 'async-only');
+    }
     async read(opts) {
         const query = this.client(this.s().uc_data_store_ucs_dataset_name);
         // Filter
@@ -100,6 +101,9 @@ let KnexUCDataStore = class KnexUCDataStore {
         const records = await query;
         return records;
     }
+    async startTx() {
+        return this.client.transaction();
+    }
     supportedSpecificBindings() {
         const type = this.s().knex_uc_data_store_type;
         switch (type) {
@@ -113,7 +117,7 @@ let KnexUCDataStore = class KnexUCDataStore {
         }
     }
     async testKey(_encryptionKey) {
-        throw new Error('Not available for this implementation.');
+        throw new NotAvailableError('testKey');
     }
     async write(record, opts) {
         await this.writeBulk([record], opts);

package/dist/esm/uc/impl/SimpleUCManager.d.ts

@@ -32,7 +32,7 @@ export declare class SimpleUCManager implements UCManager {
     execClient<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>): Promise<UCOutputReader<I, OPI0, OPI1>>;
     execServer<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>): Promise<UCOutputOrNothing<OPI0, OPI1>>;
     initServer<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>): Promise<void>;
-    initTx(): Promise<void>;
+    startTx(): Promise<void>;
     persist<I extends UCInput | undefined = undefined, D extends UCData | null = null, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>, data?: D, opts?: UCManagerPersistOpts): Promise<UCDataStoreRecord<I, D>>;
     persistProjection<T extends object>(name: string, data: T): Promise<void>;
     rollbackTx(): Promise<void>;

package/dist/esm/uc/impl/SimpleUCManager.js

@@ -116,9 +116,9 @@ let SimpleUCManager = class SimpleUCManager {
         const init = (await this.ucInitProvider(server.init));
         await init.exec();
     }
-    async initTx() {
+    async startTx() {
         this.tx = {
-            ref: await this.ucDataStore.initTx(),
+            ref: await this.ucDataStore.startTx(),
         };
     }
     async persist(uc, data, opts) {

package/dist/esm/uc/manager.d.ts

@@ -29,7 +29,7 @@ export interface UCManager {
     execClient<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>): Promise<UCOutputReader<I, OPI0, OPI1>>;
     execServer<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>): Promise<UCOutputOrNothing<OPI0, OPI1>>;
     initServer<I extends UCInput | undefined = undefined, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>): Promise<void>;
-    initTx(): Promise<void>;
+    startTx(): Promise<void>;
     persist<I extends UCInput | undefined = undefined, D extends UCData | null = null, OPI0 extends UCOPIBase | undefined = undefined, OPI1 extends UCOPIBase | undefined = undefined>(uc: UC<I, OPI0, OPI1>, data?: D, opts?: UCManagerPersistOpts): Promise<UCDataStoreRecord<I, D>>;
     persistProjection<T extends object>(name: string, data: T): Promise<void>;
     rollbackTx(): Promise<void>;

package/dist/esm/uc/settings/consts.js

@@ -1,5 +1,5 @@
 export const UC_DEFAULT_SETTINGS = {
-    uc_data_store_ucs_dataset_name: 'use-cases',
+    uc_data_store_ucs_dataset_name: 'uc_executions',
     uc_disabled_use_cases: [],
     uc_file_ref_prefix: '$ref:',
     uc_files_directory_path: 'tmp',

package/dist/esm/utils/concerns/Initializable.d.ts

@@ -1,3 +1,4 @@
 export interface Initializable {
     init(): Promise<void>;
+    initSync(): void;
 }

package/dist/esm/utils/ioc/bindCloudflareWorker.d.ts

@@ -0,0 +1,2 @@
+import type { Container } from 'inversify';
+export declare function bindCloudflareWorker(container: Container): void;

package/dist/esm/utils/ioc/bindCloudflareWorker.js

@@ -0,0 +1,15 @@
+import { NodeBufferManager } from '../../std/impl/NodeBufferManager.js';
+import { NodeCryptoManager } from '../../std/impl/NodeCryptoManager.js';
+import { NodeEnvironmentManager } from '../../std/impl/NodeEnvironmentManager.js';
+import { WebFSManager } from '../../std/impl/WebFSManager.js';
+export function bindCloudflareWorker(container) {
+    // Reusing the Node.js implementations available with the `nodejs_compat` compatibility flag
+    // https://developers.cloudflare.com/workers/runtime-apis/nodejs/#supported-nodejs-apis
+    // std
+    container.bind('BufferManager').to(NodeBufferManager);
+    container.bind('CryptoManager').to(NodeCryptoManager);
+    container
+        .bind('EnvironmentManager')
+        .to(NodeEnvironmentManager);
+    container.bind('FSManager').to(WebFSManager);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "libmodulor",
     "description": "A TypeScript library to create platform-agnostic applications",
-    "version": "0.18.1",
+    "version": "0.20.0",
     "license": "LGPL-3.0",
     "author": "Chafik H'nini <chafik.hnini@gmail.com>",
     "homepage": "https://libmodulor.c100k.eu",
@@ -23,6 +23,9 @@
         ".": {
             "import": "./dist/esm/index.js"
         },
+        "./cloudflare-worker-hono": {
+            "import": "./dist/esm/index.cloudflare-worker-hono.js"
+        },
         "./locales/en": {
             "import": "./dist/esm/i18n/locales/en.js"
         },
@@ -78,32 +81,32 @@
         "lint:ci": "biome check"
     },
     "devDependencies": {
-        "@biomejs/biome": "^2.0.0-beta.6"
+        "@biomejs/biome": "^2.1.2"
     },
     "peerDependencies": {
-        "@hono/node-server": "^1.14.3",
-        "@modelcontextprotocol/sdk": "^1.12.1",
-        "@stricli/core": "^1.1.2",
+        "@hono/node-server": "^1.17.1",
+        "@modelcontextprotocol/sdk": "^1.16.0",
+        "@stricli/core": "^1.2.0",
         "buffer": "^6.0.3",
         "cookie-parser": "^1.4.7",
         "express": "^5.1.0",
-        "express-fileupload": "^1.5.1",
-        "fast-check": "^4.1.1",
+        "express-fileupload": "^1.5.2",
+        "fast-check": "^4.2.0",
         "helmet": "^8.1.0",
-        "hono": "^4.7.11",
-        "inversify": "^7.5.2",
-        "jose": "^6.0.11",
+        "hono": "^4.8.5",
+        "inversify": "^7.6.1",
+        "jose": "^6.0.12",
         "knex": "^3.1.0",
-        "next": "^15.3.3",
-        "pg": "^8.16.0",
+        "next": "^15.4.2",
+        "pg": "^8.16.3",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
-        "react-native": "^0.79.2",
+        "react-native": "^0.79.5",
         "reflect-metadata": "^0.2.2",
         "sqlite3": "^5.1.7",
         "typescript": "^5.8.3",
         "vite": "^6.3.5",
-        "vitest": "^3.2.0"
+        "vitest": "^3.2.4"
     },
     "peerDependenciesMeta": {
         "@hono/node-server": {

package/pnpm-workspace.yaml

@@ -1,6 +1,6 @@
 packages:
-  - docs-fd
   - examples/basic
+  - examples/standalone
   - examples/supertrader
 onlyBuiltDependencies:
   - '@biomejs/biome'

package/tsconfig.json

@@ -28,7 +28,6 @@
     },
     "exclude": [
         "dist",
-        "docs-fd",
         "examples/**/dist",
         "examples/**/node_modules",
         "node_modules"