@quatrain/okf 1.0.1

package/README.md

@@ -0,0 +1,17 @@
+# @quatrain/okf
+
+Open Knowledge Format (OKF) flat file storage adapter for the Quatrain Core framework.
+
+## Overview
+
+The `@quatrain/okf` package provides a file-based persistence adapter (`OKFBackendAdapter`) that serializes Quatrain `PersistedBaseObject` entities into a structured flat file filesystem directory conforming to the OKF format.
+
+This adapter is specifically designed to facilitate local-first, offline-first architectures by excluding relational databases and utilizing structured directory trees containing lightweight JSON files.
+
+## Features
+
+- **Decoupled Architecture:** Pure filesystem storage format independent of underlying Git versioning or synchronization layers.
+- **Operator Auditing:** Automatically stores the operator's email in the document's metadata block (`meta.created_by`) for full change traceability.
+- **Hierarchical Layouts:**
+  - Telemetry: Saved as `telemetry/YYYY-MM-DD/{type}/{HHMMSS}-{millis}-{bassinId}.json`
+  - Other: Saved as `{collection}/{uid}.json`

package/dist/OKFBackendAdapter.d.ts

@@ -0,0 +1,80 @@
+import { AbstractBackendAdapter, BackendParameters, DataObjectClass, QueryResultType, Filters, Filter, SortAndLimit } from '@quatrain/backend';
+/**
+ * File-based persistence adapter conforming to the Open Knowledge Format (OKF) standard.
+ * Serializes entities into flat directory layouts.
+ */
+export declare class OKFBackendAdapter extends AbstractBackendAdapter {
+    protected dataDir: string;
+    /**
+     * Instantiates the OKF storage adapter.
+     *
+     * @param params - Configuration parameters containing database path and optional settings.
+     */
+    constructor(params?: BackendParameters);
+    /**
+     * Resolves the relative storage path matching the OKF collection and metadata hierarchy.
+     * For telemetry: telemetry/YYYY-MM-DD/{type}/{HHMMSS}-{millis}-{bassinId}.json
+     * For other: {collection}/{uid}.json
+     *
+     * @param dao - The data object model being persisted.
+     * @param uid - The unique identifier of the record.
+     * @returns The relative file path string.
+     */
+    getOKFPath(dao: DataObjectClass<any>, uid: string): string;
+    /**
+     * Creates a new JSON document on disk matching the OKF structure.
+     *
+     * @param dao - The payload object.
+     * @param desiredUid - Optional custom UID.
+     * @returns The hydrated DataObject.
+     */
+    create(dao: DataObjectClass<any>, desiredUid?: string): Promise<DataObjectClass<any>>;
+    /**
+     * Hydrates a DataObject by reading its matching flat file on disk.
+     *
+     * @param dao - The target skeleton DataObject.
+     * @returns The populated DataObject.
+     */
+    read(dao: DataObjectClass<any>): Promise<DataObjectClass<any>>;
+    /**
+     * Overwrites the JSON document with the updated payload.
+     *
+     * @param dao - The modified payload.
+     * @returns The DataObject instance.
+     */
+    update(dao: DataObjectClass<any>): Promise<DataObjectClass<any>>;
+    /**
+     * Deletes the JSON file from the filesystem.
+     *
+     * @param dao - The target DataObject to remove.
+     * @returns The cleared DataObject.
+     */
+    delete(dao: DataObjectClass<any>): Promise<DataObjectClass<any>>;
+    /**
+     * Recursively removes the directory associated with a collection.
+     *
+     * @param collection - The collection folder path to clear.
+     */
+    deleteCollection(collection: string): Promise<void>;
+    /**
+     * Helper to flatten filters into a simple array.
+     */
+    protected _flattenFilters(f?: Filters | Filter[]): Filter[];
+    /**
+     * Queries the local files by scanning directories and evaluating conditions in-memory.
+     *
+     * @param dataObject - Base template representing the target collection.
+     * @param filters - Active constraints.
+     * @param pagination - Limits and sorting directives.
+     * @returns QueryResult containing found items and diagnostics.
+     */
+    find(dataObject: DataObjectClass<any>, filters?: Filters | Filter[], pagination?: SortAndLimit): Promise<QueryResultType<any>>;
+    generateCreateSql(): {
+        upSql: string;
+        downSql: string;
+    };
+    generateDeltaSql(): {
+        upSql: never[];
+        downSql: never[];
+    };
+}

package/dist/OKFBackendAdapter.js

@@ -0,0 +1,297 @@
+"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 __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;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OKFBackendAdapter = void 0;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+const backend_1 = require("@quatrain/backend");
+const core_1 = require("@quatrain/core");
+/**
+ * File-based persistence adapter conforming to the Open Knowledge Format (OKF) standard.
+ * Serializes entities into flat directory layouts.
+ */
+class OKFBackendAdapter extends backend_1.AbstractBackendAdapter {
+    /**
+     * Instantiates the OKF storage adapter.
+     *
+     * @param params - Configuration parameters containing database path and optional settings.
+     */
+    constructor(params) {
+        var _a;
+        const actualParams = params || {};
+        super(actualParams);
+        this.dataDir = ((_a = actualParams.config) === null || _a === void 0 ? void 0 : _a.database) || process.env.STUDIO_DATA_DIR || '/data/okf';
+    }
+    /**
+     * Resolves the relative storage path matching the OKF collection and metadata hierarchy.
+     * For telemetry: telemetry/YYYY-MM-DD/{type}/{HHMMSS}-{millis}-{bassinId}.json
+     * For other: {collection}/{uid}.json
+     *
+     * @param dao - The data object model being persisted.
+     * @param uid - The unique identifier of the record.
+     * @returns The relative file path string.
+     */
+    getOKFPath(dao, uid) {
+        const collection = this.getCollection(dao);
+        if (!collection) {
+            throw new backend_1.BackendError("[OKF] Cannot resolve path without collection name");
+        }
+        if (collection === 'telemetry') {
+            const createdAt = dao.val('createdAt') || new Date().toISOString();
+            const dateObj = new Date(createdAt);
+            const yyyymmdd = dateObj.toISOString().split('T')[0];
+            const timePart = dateObj.toISOString().split('T')[1].replace(/Z/g, '');
+            const parts = timePart.split('.');
+            const hms = parts[0];
+            const ms = parts[1];
+            const hhmmsstrim = hms.replace(/:/g, '');
+            const millis = ms ? ms.substring(0, 3) : '000';
+            const type = dao.val('type') || 'o2';
+            const bassinId = dao.val('bassin') || 'unknown';
+            return path.join('telemetry', yyyymmdd, type, `${hhmmsstrim}-${millis}-${bassinId}.json`);
+        }
+        return path.join(collection, `${uid}.json`);
+    }
+    /**
+     * Creates a new JSON document on disk matching the OKF structure.
+     *
+     * @param dao - The payload object.
+     * @param desiredUid - Optional custom UID.
+     * @returns The hydrated DataObject.
+     */
+    create(dao, desiredUid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const uid = desiredUid || dao.val('id') || crypto.randomUUID();
+            const relativePath = this.getOKFPath(dao, uid);
+            const fullPath = path.join(this.dataDir, relativePath);
+            const payload = {
+                meta: {
+                    version: '1.0',
+                    created_by: dao.val('createdBy') || 'operator@sodav.ci',
+                    created_at: dao.val('createdAt') || new Date().toISOString()
+                },
+                data: dao.toJSON()
+            };
+            yield fs.mkdir(path.dirname(fullPath), { recursive: true });
+            yield fs.writeFile(fullPath, JSON.stringify(payload, null, 2), 'utf-8');
+            dao.uri = new core_1.ObjectUri(`${this.getCollection(dao)}/${uid}`);
+            return dao;
+        });
+    }
+    /**
+     * Hydrates a DataObject by reading its matching flat file on disk.
+     *
+     * @param dao - The target skeleton DataObject.
+     * @returns The populated DataObject.
+     */
+    read(dao) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const uid = dao.uri.uid;
+            if (!uid) {
+                throw new backend_1.BackendError("[OKF] Cannot read record without a valid UID");
+            }
+            const relativePath = this.getOKFPath(dao, uid);
+            const fullPath = path.join(this.dataDir, relativePath);
+            try {
+                const raw = yield fs.readFile(fullPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                return yield dao.populate(parsed.data);
+            }
+            catch (err) {
+                throw new core_1.NotFoundError(`[OKF] Record not found at path: ${relativePath}`);
+            }
+        });
+    }
+    /**
+     * Overwrites the JSON document with the updated payload.
+     *
+     * @param dao - The modified payload.
+     * @returns The DataObject instance.
+     */
+    update(dao) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const uid = dao.uri.uid;
+            if (!uid) {
+                throw new backend_1.BackendError("[OKF] Cannot update record without a valid UID");
+            }
+            const relativePath = this.getOKFPath(dao, uid);
+            const fullPath = path.join(this.dataDir, relativePath);
+            const payload = {
+                meta: {
+                    version: '1.0',
+                    created_by: dao.val('createdBy') || 'operator@sodav.ci',
+                    created_at: dao.val('createdAt') || new Date().toISOString()
+                },
+                data: dao.toJSON()
+            };
+            yield fs.writeFile(fullPath, JSON.stringify(payload, null, 2), 'utf-8');
+            return dao;
+        });
+    }
+    /**
+     * Deletes the JSON file from the filesystem.
+     *
+     * @param dao - The target DataObject to remove.
+     * @returns The cleared DataObject.
+     */
+    delete(dao) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const uid = dao.uri.uid;
+            if (!uid) {
+                throw new backend_1.BackendError("[OKF] Cannot delete record without a valid UID");
+            }
+            const relativePath = this.getOKFPath(dao, uid);
+            const fullPath = path.join(this.dataDir, relativePath);
+            try {
+                yield fs.unlink(fullPath);
+            }
+            catch (err) {
+                throw new core_1.NotFoundError(`[OKF] Failed to delete record at path: ${relativePath}`);
+            }
+            return dao;
+        });
+    }
+    /**
+     * Recursively removes the directory associated with a collection.
+     *
+     * @param collection - The collection folder path to clear.
+     */
+    deleteCollection(collection) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const colPath = path.join(this.dataDir, collection);
+            yield fs.rm(colPath, { recursive: true, force: true });
+        });
+    }
+    /**
+     * Helper to flatten filters into a simple array.
+     */
+    _flattenFilters(f) {
+        if (!f)
+            return [];
+        if (Array.isArray(f))
+            return f;
+        const list = [];
+        if (f.and)
+            list.push(...f.and);
+        if (f.or)
+            list.push(...f.or);
+        return list;
+    }
+    /**
+     * Queries the local files by scanning directories and evaluating conditions in-memory.
+     *
+     * @param dataObject - Base template representing the target collection.
+     * @param filters - Active constraints.
+     * @param pagination - Limits and sorting directives.
+     * @returns QueryResult containing found items and diagnostics.
+     */
+    find(dataObject, filters, pagination) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const collection = this.getCollection(dataObject);
+            if (!collection) {
+                throw new backend_1.BackendError("[OKF] Cannot query without a valid collection name");
+            }
+            const items = [];
+            const baseColPath = path.join(this.dataDir, collection);
+            const scanDir = (dir) => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    const entries = yield fs.readdir(dir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        const fullPath = path.join(dir, entry.name);
+                        if (entry.isDirectory()) {
+                            yield scanDir(fullPath);
+                        }
+                        else if (entry.isFile() && entry.name.endsWith('.json')) {
+                            const content = yield fs.readFile(fullPath, 'utf-8');
+                            const parsed = JSON.parse(content);
+                            const dao = yield dataObject.clone(parsed.data);
+                            let keep = true;
+                            if (filters) {
+                                const filterArr = this._flattenFilters(filters);
+                                for (const filter of filterArr) {
+                                    const prop = dao.get(filter.prop);
+                                    if (typeof prop === 'undefined') {
+                                        keep = false;
+                                        break;
+                                    }
+                                    if (prop.val() !== filter.value) {
+                                        keep = false;
+                                        break;
+                                    }
+                                }
+                            }
+                            if (keep) {
+                                items.push(dao);
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    // Ignore missing folders
+                }
+            });
+            yield scanDir(baseColPath);
+            // Simple slice implementation for limit/offset
+            let slicedItems = items;
+            if (pagination && pagination.limits) {
+                const offset = pagination.limits.offset || 0;
+                const batch = pagination.limits.batch || items.length;
+                slicedItems = items.slice(offset, offset + batch);
+            }
+            return {
+                items: slicedItems,
+                meta: {
+                    count: items.length,
+                    offset: (pagination === null || pagination === void 0 ? void 0 : pagination.limits.offset) || 0,
+                    batch: (pagination === null || pagination === void 0 ? void 0 : pagination.limits.batch) || items.length,
+                    executionTime: Date.now()
+                }
+            };
+        });
+    }
+    generateCreateSql() { return { upSql: '', downSql: '' }; }
+    generateDeltaSql() { return { upSql: [], downSql: [] }; }
+}
+exports.OKFBackendAdapter = OKFBackendAdapter;

package/dist/OKFBackendAdapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/OKFBackendAdapter.test.js

@@ -0,0 +1,128 @@
+"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 __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;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const OKFBackendAdapter_1 = require("./OKFBackendAdapter");
+const backend_1 = require("@quatrain/backend");
+const backend_2 = require("@quatrain/backend");
+const core_1 = require("@quatrain/core");
+class OKFTestObject extends backend_2.PersistedBaseObject {
+}
+OKFTestObject.COLLECTION = 'test_collection';
+OKFTestObject.PROPS_DEFINITION = [
+    { name: 'name', type: core_1.StringProperty.TYPE },
+    { name: 'createdBy', type: core_1.StringProperty.TYPE }
+];
+class OKFTelemetryObject extends backend_2.PersistedBaseObject {
+}
+OKFTelemetryObject.COLLECTION = 'telemetry';
+OKFTelemetryObject.PROPS_DEFINITION = [
+    { name: 'type', type: core_1.StringProperty.TYPE },
+    { name: 'bassin', type: core_1.StringProperty.TYPE },
+    { name: 'createdAt', type: core_1.DateTimeProperty.TYPE },
+    { name: 'createdBy', type: core_1.StringProperty.TYPE }
+];
+describe('OKFBackendAdapter', () => {
+    const testDir = path.resolve(__dirname, '__test_okf_data__');
+    let adapter;
+    beforeAll(() => __awaiter(void 0, void 0, void 0, function* () {
+        yield fs.mkdir(testDir, { recursive: true });
+        adapter = new OKFBackendAdapter_1.OKFBackendAdapter({
+            config: { database: testDir }
+        });
+        backend_1.Backend.addBackend(adapter, 'okf_test', true);
+    }));
+    afterAll(() => __awaiter(void 0, void 0, void 0, function* () {
+        yield fs.rm(testDir, { recursive: true, force: true });
+    }));
+    test('should format relative OKF filepath correctly for regular objects', () => __awaiter(void 0, void 0, void 0, function* () {
+        const obj = yield OKFTestObject.factory();
+        const relativePath = adapter.getOKFPath(obj.dataObject, '123-abc');
+        expect(relativePath).toBe(path.join('test_collection', '123-abc.json'));
+    }));
+    test('should format relative OKF filepath correctly for telemetry', () => __awaiter(void 0, void 0, void 0, function* () {
+        const dateString = '2026-07-12T14:30:45.120Z';
+        const obj = yield OKFTelemetryObject.factory();
+        obj.set('type', 'ph');
+        obj.set('bassin', 'bac-04');
+        obj.set('createdAt', dateString);
+        const relativePath = adapter.getOKFPath(obj.dataObject, 'some-uid');
+        // Should result in telemetry/2026-07-12/ph/143045-120-bac-04.json
+        expect(relativePath).toBe(path.join('telemetry', '2026-07-12', 'ph', '143045-120-bac-04.json'));
+    }));
+    test('should perform CRUD operations', () => __awaiter(void 0, void 0, void 0, function* () {
+        // 1. Create
+        const obj = yield OKFTestObject.factory();
+        obj.set('name', 'Poisson Tilapia');
+        obj.set('createdBy', 'pascal@sodav.ci');
+        yield obj.save();
+        expect(obj.dataObject.uri.uid).toBeDefined();
+        const savedUid = obj.dataObject.uri.uid;
+        const expectedPath = path.join(testDir, 'test_collection', `${savedUid}.json`);
+        const fileExists = yield fs.stat(expectedPath).then(() => true).catch(() => false);
+        expect(fileExists).toBe(true);
+        // Verify file content structure
+        const raw = yield fs.readFile(expectedPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        expect(parsed.meta.created_by).toBe('pascal@sodav.ci');
+        expect(parsed.data.name).toBe('Poisson Tilapia');
+        // 2. Read
+        const loaded = yield OKFTestObject.fromBackend(savedUid);
+        expect(loaded.val('name')).toBe('Poisson Tilapia');
+        // 3. Update
+        loaded.set('name', 'Tilapia Rouge');
+        yield loaded.save();
+        const loaded2 = yield OKFTestObject.fromBackend(savedUid);
+        expect(loaded2.val('name')).toBe('Tilapia Rouge');
+        // 4. Find
+        const results = yield OKFTestObject.repository().query(OKFTestObject.query());
+        expect(results.items.length).toBe(1);
+        expect(results.items[0].val('name')).toBe('Tilapia Rouge');
+        // 5. Delete
+        yield loaded2.delete();
+        const fileExistsAfterDelete = yield fs.stat(expectedPath).then(() => true).catch(() => false);
+        expect(fileExistsAfterDelete).toBe(false);
+    }));
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './OKFBackendAdapter';

package/dist/index.js

@@ -0,0 +1,17 @@
+"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("./OKFBackendAdapter"), exports);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@quatrain/okf",
+  "version": "1.0.1",
+  "description": "Open Knowledge Format (OKF) flat file storage adapter",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bun": "src/index.ts",
+  "files": [
+    "LICENSE.md",
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Quatrain/Core.git",
+    "directory": "packages/okf"
+  },
+  "author": "Quatrain Développement SAS <developers@quatrain.com>",
+  "license": "AGPL-3.0-only",
+  "devDependencies": {
+    "@tsconfig/recommended": "^1.0.1",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.10.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "@quatrain/backend": "^1.2.17",
+    "@quatrain/log": "^1.2.4",
+    "@quatrain/types": "^1.2.16"
+  },
+  "scripts": {
+    "test-ci": "jest --runInBand",
+    "build": "tsc"
+  }
+}

package/src/OKFBackendAdapter.test.ts

@@ -0,0 +1,100 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { OKFBackendAdapter } from './OKFBackendAdapter';
+import { Backend } from '@quatrain/backend';
+import { PersistedBaseObject } from '@quatrain/backend';
+import { StringProperty, DateTimeProperty } from '@quatrain/core';
+
+class OKFTestObject extends PersistedBaseObject {
+   static COLLECTION = 'test_collection';
+   static PROPS_DEFINITION = [
+      { name: 'name', type: StringProperty.TYPE },
+      { name: 'createdBy', type: StringProperty.TYPE }
+   ];
+}
+
+class OKFTelemetryObject extends PersistedBaseObject {
+   static COLLECTION = 'telemetry';
+   static PROPS_DEFINITION = [
+      { name: 'type', type: StringProperty.TYPE },
+      { name: 'bassin', type: StringProperty.TYPE },
+      { name: 'createdAt', type: DateTimeProperty.TYPE },
+      { name: 'createdBy', type: StringProperty.TYPE }
+   ];
+}
+
+describe('OKFBackendAdapter', () => {
+   const testDir = path.resolve(__dirname, '__test_okf_data__');
+   let adapter: OKFBackendAdapter;
+
+   beforeAll(async () => {
+      await fs.mkdir(testDir, { recursive: true });
+      adapter = new OKFBackendAdapter({
+         config: { database: testDir }
+      });
+      Backend.addBackend(adapter, 'okf_test', true);
+   });
+
+   afterAll(async () => {
+      await fs.rm(testDir, { recursive: true, force: true });
+   });
+
+   test('should format relative OKF filepath correctly for regular objects', async () => {
+      const obj = await OKFTestObject.factory();
+      const relativePath = adapter.getOKFPath(obj.dataObject, '123-abc');
+      expect(relativePath).toBe(path.join('test_collection', '123-abc.json'));
+   });
+
+   test('should format relative OKF filepath correctly for telemetry', async () => {
+      const dateString = '2026-07-12T14:30:45.120Z';
+      const obj = await OKFTelemetryObject.factory();
+      obj.set('type', 'ph');
+      obj.set('bassin', 'bac-04');
+      obj.set('createdAt', dateString);
+
+      const relativePath = adapter.getOKFPath(obj.dataObject, 'some-uid');
+      // Should result in telemetry/2026-07-12/ph/143045-120-bac-04.json
+      expect(relativePath).toBe(path.join('telemetry', '2026-07-12', 'ph', '143045-120-bac-04.json'));
+   });
+
+   test('should perform CRUD operations', async () => {
+      // 1. Create
+      const obj = await OKFTestObject.factory();
+      obj.set('name', 'Poisson Tilapia');
+      obj.set('createdBy', 'pascal@sodav.ci');
+      await obj.save();
+      expect(obj.dataObject.uri.uid).toBeDefined();
+
+      const savedUid = obj.dataObject.uri.uid;
+      const expectedPath = path.join(testDir, 'test_collection', `${savedUid}.json`);
+      const fileExists = await fs.stat(expectedPath).then(() => true).catch(() => false);
+      expect(fileExists).toBe(true);
+
+      // Verify file content structure
+      const raw = await fs.readFile(expectedPath, 'utf-8');
+      const parsed = JSON.parse(raw);
+      expect(parsed.meta.created_by).toBe('pascal@sodav.ci');
+      expect(parsed.data.name).toBe('Poisson Tilapia');
+
+      // 2. Read
+      const loaded = await OKFTestObject.fromBackend<OKFTestObject>(savedUid);
+      expect(loaded.val('name')).toBe('Poisson Tilapia');
+
+      // 3. Update
+      loaded.set('name', 'Tilapia Rouge');
+      await loaded.save();
+
+      const loaded2 = await OKFTestObject.fromBackend<OKFTestObject>(savedUid);
+      expect(loaded2.val('name')).toBe('Tilapia Rouge');
+
+      // 4. Find
+      const results = await OKFTestObject.repository().query(OKFTestObject.query());
+      expect(results.items.length).toBe(1);
+      expect(results.items[0].val('name')).toBe('Tilapia Rouge');
+
+      // 5. Delete
+      await loaded2.delete();
+      const fileExistsAfterDelete = await fs.stat(expectedPath).then(() => true).catch(() => false);
+      expect(fileExistsAfterDelete).toBe(false);
+   });
+});

package/src/OKFBackendAdapter.ts

@@ -0,0 +1,271 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { 
+   AbstractBackendAdapter, 
+   BackendParameters, 
+   DataObjectClass,
+   QueryResultType,
+   Filters,
+   Filter,
+   SortAndLimit,
+   BackendError
+} from '@quatrain/backend';
+import { ObjectUri, NotFoundError } from '@quatrain/core';
+
+/**
+ * File-based persistence adapter conforming to the Open Knowledge Format (OKF) standard.
+ * Serializes entities into flat directory layouts.
+ */
+export class OKFBackendAdapter extends AbstractBackendAdapter {
+   protected dataDir: string;
+
+   /**
+    * Instantiates the OKF storage adapter.
+    * 
+    * @param params - Configuration parameters containing database path and optional settings.
+    */
+   constructor(params?: BackendParameters) {
+      const actualParams = params || {};
+      super(actualParams);
+      this.dataDir = (actualParams.config?.database as string) || process.env.STUDIO_DATA_DIR || '/data/okf';
+   }
+
+   /**
+    * Resolves the relative storage path matching the OKF collection and metadata hierarchy.
+    * For telemetry: telemetry/YYYY-MM-DD/{type}/{HHMMSS}-{millis}-{bassinId}.json
+    * For other: {collection}/{uid}.json
+    * 
+    * @param dao - The data object model being persisted.
+    * @param uid - The unique identifier of the record.
+    * @returns The relative file path string.
+    */
+   public getOKFPath(dao: DataObjectClass<any>, uid: string): string {
+      const collection = this.getCollection(dao);
+      if (!collection) {
+         throw new BackendError("[OKF] Cannot resolve path without collection name");
+      }
+      
+      if (collection === 'telemetry') {
+         const createdAt = dao.val('createdAt') || new Date().toISOString();
+         const dateObj = new Date(createdAt);
+         const yyyymmdd = dateObj.toISOString().split('T')[0];
+         const timePart = dateObj.toISOString().split('T')[1].replace(/Z/g, '');
+         const parts = timePart.split('.');
+         const hms = parts[0];
+         const ms = parts[1];
+         const hhmmsstrim = hms.replace(/:/g, '');
+         const millis = ms ? ms.substring(0, 3) : '000';
+         const type = dao.val('type') || 'o2';
+         const bassinId = dao.val('bassin') || 'unknown';
+         return path.join('telemetry', yyyymmdd, type, `${hhmmsstrim}-${millis}-${bassinId}.json`);
+      }
+
+      return path.join(collection, `${uid}.json`);
+   }
+
+   /**
+    * Creates a new JSON document on disk matching the OKF structure.
+    * 
+    * @param dao - The payload object.
+    * @param desiredUid - Optional custom UID.
+    * @returns The hydrated DataObject.
+    */
+   async create(dao: DataObjectClass<any>, desiredUid?: string): Promise<DataObjectClass<any>> {
+      const uid: string = desiredUid || (dao.val('id') as string) || crypto.randomUUID();
+      const relativePath = this.getOKFPath(dao, uid);
+      const fullPath = path.join(this.dataDir, relativePath);
+
+      const payload = {
+         meta: {
+            version: '1.0',
+            created_by: dao.val('createdBy') || 'operator@sodav.ci',
+            created_at: dao.val('createdAt') || new Date().toISOString()
+         },
+         data: dao.toJSON()
+      };
+
+      await fs.mkdir(path.dirname(fullPath), { recursive: true });
+      await fs.writeFile(fullPath, JSON.stringify(payload, null, 2), 'utf-8');
+
+      dao.uri = new ObjectUri(`${this.getCollection(dao)}/${uid}`);
+      return dao;
+   }
+
+   /**
+    * Hydrates a DataObject by reading its matching flat file on disk.
+    * 
+    * @param dao - The target skeleton DataObject.
+    * @returns The populated DataObject.
+    */
+   async read(dao: DataObjectClass<any>): Promise<DataObjectClass<any>> {
+      const uid = dao.uri.uid;
+      if (!uid) {
+         throw new BackendError("[OKF] Cannot read record without a valid UID");
+      }
+      const relativePath = this.getOKFPath(dao, uid);
+      const fullPath = path.join(this.dataDir, relativePath);
+
+      try {
+         const raw = await fs.readFile(fullPath, 'utf-8');
+         const parsed = JSON.parse(raw);
+         return await dao.populate(parsed.data);
+      } catch (err) {
+         throw new NotFoundError(`[OKF] Record not found at path: ${relativePath}`);
+      }
+   }
+
+   /**
+    * Overwrites the JSON document with the updated payload.
+    * 
+    * @param dao - The modified payload.
+    * @returns The DataObject instance.
+    */
+   async update(dao: DataObjectClass<any>): Promise<DataObjectClass<any>> {
+      const uid = dao.uri.uid;
+      if (!uid) {
+         throw new BackendError("[OKF] Cannot update record without a valid UID");
+      }
+      const relativePath = this.getOKFPath(dao, uid);
+      const fullPath = path.join(this.dataDir, relativePath);
+
+      const payload = {
+         meta: {
+            version: '1.0',
+            created_by: dao.val('createdBy') || 'operator@sodav.ci',
+            created_at: dao.val('createdAt') || new Date().toISOString()
+         },
+         data: dao.toJSON()
+      };
+
+      await fs.writeFile(fullPath, JSON.stringify(payload, null, 2), 'utf-8');
+      return dao;
+   }
+
+   /**
+    * Deletes the JSON file from the filesystem.
+    * 
+    * @param dao - The target DataObject to remove.
+    * @returns The cleared DataObject.
+    */
+   async delete(dao: DataObjectClass<any>): Promise<DataObjectClass<any>> {
+      const uid = dao.uri.uid;
+      if (!uid) {
+         throw new BackendError("[OKF] Cannot delete record without a valid UID");
+      }
+      const relativePath = this.getOKFPath(dao, uid);
+      const fullPath = path.join(this.dataDir, relativePath);
+
+      try {
+         await fs.unlink(fullPath);
+      } catch (err) {
+         throw new NotFoundError(`[OKF] Failed to delete record at path: ${relativePath}`);
+      }
+
+      return dao;
+   }
+
+   /**
+    * Recursively removes the directory associated with a collection.
+    * 
+    * @param collection - The collection folder path to clear.
+    */
+   async deleteCollection(collection: string): Promise<void> {
+      const colPath = path.join(this.dataDir, collection);
+      await fs.rm(colPath, { recursive: true, force: true });
+   }
+
+   /**
+    * Helper to flatten filters into a simple array.
+    */
+   protected _flattenFilters(f?: Filters | Filter[]): Filter[] {
+      if (!f) return [];
+      if (Array.isArray(f)) return f;
+      const list: Filter[] = [];
+      if (f.and) list.push(...f.and);
+      if (f.or) list.push(...f.or);
+      return list;
+   }
+
+   /**
+    * Queries the local files by scanning directories and evaluating conditions in-memory.
+    * 
+    * @param dataObject - Base template representing the target collection.
+    * @param filters - Active constraints.
+    * @param pagination - Limits and sorting directives.
+    * @returns QueryResult containing found items and diagnostics.
+    */
+   async find(
+      dataObject: DataObjectClass<any>,
+      filters?: Filters | Filter[],
+      pagination?: SortAndLimit
+   ): Promise<QueryResultType<any>> {
+      const collection = this.getCollection(dataObject);
+      if (!collection) {
+         throw new BackendError("[OKF] Cannot query without a valid collection name");
+      }
+      const items: DataObjectClass<any>[] = [];
+      const baseColPath = path.join(this.dataDir, collection);
+      
+      const scanDir = async (dir: string) => {
+         try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+               const fullPath = path.join(dir, entry.name);
+               if (entry.isDirectory()) {
+                  await scanDir(fullPath);
+               } else if (entry.isFile() && entry.name.endsWith('.json')) {
+                  const content = await fs.readFile(fullPath, 'utf-8');
+                  const parsed = JSON.parse(content);
+                  const dao = await dataObject.clone(parsed.data);
+                  
+                  let keep = true;
+                  if (filters) {
+                     const filterArr = this._flattenFilters(filters);
+                     for (const filter of filterArr) {
+                        const prop = dao.get(filter.prop);
+                        if (typeof prop === 'undefined') {
+                           keep = false;
+                           break;
+                        }
+                        if (prop.val() !== filter.value) {
+                           keep = false;
+                           break;
+                        }
+                     }
+                  }
+                  
+                  if (keep) {
+                     items.push(dao);
+                  }
+               }
+            }
+         } catch (err) {
+            // Ignore missing folders
+         }
+      };
+
+      await scanDir(baseColPath);
+
+      // Simple slice implementation for limit/offset
+      let slicedItems = items;
+      if (pagination && pagination.limits) {
+         const offset = pagination.limits.offset || 0;
+         const batch = pagination.limits.batch || items.length;
+         slicedItems = items.slice(offset, offset + batch);
+      }
+
+      return {
+         items: slicedItems,
+         meta: {
+            count: items.length,
+            offset: pagination?.limits.offset || 0,
+            batch: pagination?.limits.batch || items.length,
+            executionTime: Date.now()
+         }
+      };
+   }
+
+   generateCreateSql() { return { upSql: '', downSql: '' }; }
+   generateDeltaSql() { return { upSql: [], downSql: [] }; }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './OKFBackendAdapter'