@x12i/static-memorix-explorer-api 1.0.0

package/dist/storage/InMemoryStore.js

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONTENT_TYPES } from "../types.js";
+import { MOCKS_DIR, METADATA_DIR, DATA_DIR } from "../config.js";
+import { validateRecordArray } from "../engine/identity.js";
+import { isDir, listJsonFiles, readJson, writeJson, basenameNoExt, } from "./fs.js";
+import { DISK_FLUSH_DEBOUNCE_MS } from "../config.js";
+const DIRTY = Symbol("dirty");
+export class InMemoryStore {
+    collections = new Map(); // key: `${objectType}/${contentType}`
+    metadata = new Map();
+    flushTimers = new Map();
+    loaded = false;
+    /**
+     * Load everything from disk into memory. Idempotent.
+     */
+    async load() {
+        if (this.loaded)
+            return;
+        this.loadMetadataCatalog();
+        this.loadDataCollections();
+        this.loaded = true;
+    }
+    loadMetadataCatalog() {
+        const sections = {
+            "object-types": "object-types",
+            lists: "lists",
+            "write-descriptors": "write-descriptors",
+            narratives: "narratives",
+        };
+        for (const [subdir] of Object.entries(sections)) {
+            const dir = path.join(METADATA_DIR, subdir);
+            for (const file of listJsonFiles(dir)) {
+                const key = `${subdir}/${basenameNoExt(file)}`;
+                this.metadata.set(key, { path: file, data: readJson(file, {}) });
+            }
+        }
+        const agentsFile = path.join(METADATA_DIR, "agents.json");
+        if (fs.existsSync(agentsFile)) {
+            this.metadata.set("agents", {
+                path: agentsFile,
+                data: readJson(agentsFile, { agents: [] }),
+            });
+        }
+    }
+    loadDataCollections() {
+        if (!isDir(DATA_DIR))
+            return;
+        for (const objectType of fs.readdirSync(DATA_DIR)) {
+            const otDir = path.join(DATA_DIR, objectType);
+            if (!isDir(otDir))
+                continue;
+            for (const ct of CONTENT_TYPES) {
+                const file = path.join(otDir, `${ct}.json`);
+                const key = `${objectType}/${ct}`;
+                const data = readJson(file, []);
+                // Startup validation: ensure records carry exactly one identity key
+                // (MemorixRecordArraySchema mock). Memory collections use memoryId.
+                const result = validateRecordArray(objectType, ct, data);
+                if (!result.ok) {
+                    for (const err of result.errors) {
+                        console.warn(`[mock-memorix-explorer-api] schema warning: ${err}`);
+                    }
+                }
+                this.collections.set(key, {
+                    path: file,
+                    data,
+                });
+            }
+            // system overrides
+            const invFile = path.join(DATA_DIR, "system", "inventory.json");
+            if (objectType === "system" && fs.existsSync(invFile)) {
+                this.collections.set("system/inventory", {
+                    path: invFile,
+                    data: readJson(invFile, []),
+                });
+            }
+        }
+    }
+    // ---- Metadata access ----
+    getMeta(key) {
+        return this.metadata.get(key)?.data;
+    }
+    setMeta(key, data, persist = true) {
+        const existing = this.metadata.get(key);
+        if (existing) {
+            existing.data = data;
+            existing[DIRTY] = true;
+        }
+        else {
+            this.metadata.set(key, {
+                path: path.join(METADATA_DIR, `${key}.json`),
+                data,
+                [DIRTY]: true,
+            });
+        }
+        if (persist)
+            this.scheduleMetaFlush(key);
+    }
+    getMetaKeys() {
+        return [...this.metadata.keys()];
+    }
+    // ---- Collection access ----
+    getCollection(objectType, ct) {
+        const key = `${objectType}/${ct}`;
+        const c = this.collections.get(key);
+        if (!c) {
+            const newC = {
+                path: path.join(DATA_DIR, objectType, `${ct}.json`),
+                data: [],
+            };
+            this.collections.set(key, newC);
+            return newC.data;
+        }
+        return c.data;
+    }
+    setCollection(objectType, ct, data) {
+        const key = `${objectType}/${ct}`;
+        const c = this.collections.get(key);
+        if (c) {
+            c.data = data;
+            c[DIRTY] = true;
+        }
+        else {
+            this.collections.set(key, {
+                path: path.join(DATA_DIR, objectType, `${ct}.json`),
+                data,
+                [DIRTY]: true,
+            });
+        }
+        this.scheduleCollectionFlush(key);
+    }
+    getCollectionKeys() {
+        return [...this.collections.keys()];
+    }
+    // ---- Flush machinery ----
+    scheduleCollectionFlush(key) {
+        const existing = this.flushTimers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        const t = setTimeout(() => {
+            this.flushCollectionNow(key);
+            this.flushTimers.delete(key);
+        }, DISK_FLUSH_DEBOUNCE_MS);
+        this.flushTimers.set(key, t);
+    }
+    scheduleMetaFlush(key) {
+        const fkey = `meta:${key}`;
+        const existing = this.flushTimers.get(fkey);
+        if (existing)
+            clearTimeout(existing);
+        const t = setTimeout(() => {
+            this.flushMetaNow(key);
+            this.flushTimers.delete(fkey);
+        }, DISK_FLUSH_DEBOUNCE_MS);
+        this.flushTimers.set(fkey, t);
+    }
+    flushCollectionNow(key) {
+        const c = this.collections.get(key);
+        if (c && c[DIRTY]) {
+            writeJson(c.path, c.data);
+            c[DIRTY] = false;
+        }
+    }
+    flushMetaNow(key) {
+        const m = this.metadata.get(key);
+        if (m && m[DIRTY]) {
+            writeJson(m.path, m.data);
+            m[DIRTY] = false;
+        }
+    }
+    /**
+     * Flush every dirty file immediately and clear timers.
+     */
+    async flushAll() {
+        for (const t of this.flushTimers.values())
+            clearTimeout(t);
+        this.flushTimers.clear();
+        for (const key of this.collections.keys())
+            this.flushCollectionNow(key);
+        for (const key of this.metadata.keys())
+            this.flushMetaNow(key);
+    }
+    get mocksDir() {
+        return MOCKS_DIR;
+    }
+}
+export const store = new InMemoryStore();

package/dist/storage/fs.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function readJson(p, fallback) {
+    try {
+        const raw = fs.readFileSync(p, "utf8");
+        if (!raw.trim())
+            return fallback;
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(p, data) {
+    ensureDir(path.dirname(p));
+    fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+export function listJsonFiles(dir) {
+    if (!isDir(dir))
+        return [];
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => path.join(dir, f));
+}
+export function basenameNoExt(p) {
+    return path.basename(p, ".json");
+}

package/dist/types.js

@@ -0,0 +1,37 @@
+export const CONTENT_TYPES = [
+    "snapshots",
+    "analysis",
+    "decisions",
+    "events",
+    "memory",
+];
+/**
+ * The fourth tier of data alongside entities, events, and knowledge.
+ * `memory` collections are keyed by `memoryId`.
+ */
+export const MEMORY_CONTENT_TYPE = "memory";
+/** Primary identity keys accepted across fetch/write engines. */
+export const IDENTITY_KEYS = [
+    "recordId",
+    "entityId",
+    "eventId",
+    "knowledgeId",
+    "memoryId",
+];
+/** Map a target type to its canonical id field. */
+export const TARGET_TO_ID_FIELD = {
+    entity: "recordId",
+    event: "eventId",
+    knowledge: "knowledgeId",
+    memory: "memoryId",
+};
+export const INCLUDE_FLAGS = [
+    "data",
+    "analytics",
+    "enrichment",
+    "insights",
+    "system",
+    "associated",
+    "discovery",
+    "analysis",
+];

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@x12i/static-memorix-explorer-api",
+  "version": "1.0.0",
+  "description": "Static mock server providing full API parity for the Memorix Explorer API.",
+  "type": "module",
+  "main": "dist/server.js",
+  "exports": {
+    ".": {
+      "import": "./dist/server.js"
+    },
+    "./config": {
+      "import": "./dist/config.js"
+    }
+  },
+  "bin": {
+    "mock-memorix-explorer-api": "dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "dev": "node --experimental-strip-types server.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "postpack": "true"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "fastify": "^4.28.1",
+    "mingo": "^6.4.12"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/static-memorix-explorer-api.git"
+  },
+  "homepage": "https://github.com/x12i/static-memorix-explorer-api#readme",
+  "bugs": {
+    "url": "https://github.com/x12i/static-memorix-explorer-api/issues"
+  },
+  "keywords": [
+    "mock",
+    "api",
+    "memorix",
+    "explorer",
+    "fastify",
+    "test-server",
+    "development-tools",
+    "static"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}