@jskit-ai/storage-runtime 0.1.4

package/package.descriptor.mjs

@@ -0,0 +1,64 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/storage-runtime",
+  version: "0.1.4",
+  dependsOn: [
+    "@jskit-ai/kernel"
+  ],
+  capabilities: {
+    provides: [
+      "runtime.storage"
+    ],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providerEntrypoint: "src/server/providers/StorageRuntimeServiceProvider.js",
+      providers: [
+        {
+          entrypoint: "src/server/providers/StorageRuntimeServiceProvider.js",
+          export: "StorageRuntimeServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/providers/StorageRuntimeServiceProvider",
+          summary: "Exports storage runtime server provider."
+        },
+        {
+          subpath: "./client",
+          summary: "Exports no client runtime API today (reserved client entrypoint)."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "runtime.storage",
+          "KERNEL_TOKENS.Storage"
+        ],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/kernel": "0.1.4",
+        "unstorage": "^1.17.3"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [],
+    text: []
+  }
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@jskit-ai/storage-runtime",
+  "version": "0.1.4",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./server/providers/StorageRuntimeServiceProvider": "./src/server/providers/StorageRuntimeServiceProvider.js"
+  },
+  "dependencies": {
+    "@jskit-ai/kernel": "0.1.4",
+    "unstorage": "^1.17.3"
+  }
+}

package/src/client/index.js

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

package/src/server/providers/StorageRuntimeServiceProvider.js

@@ -0,0 +1,26 @@
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import * as storageBinding from "../storageBinding.js";
+
+const STORAGE_RUNTIME_SERVER_TOKEN = "runtime.storage";
+const STORAGE_RUNTIME_SERVER_API = Object.freeze({
+  ...storageBinding
+});
+
+class StorageRuntimeServiceProvider {
+  static id = STORAGE_RUNTIME_SERVER_TOKEN;
+
+  static dependsOn = ["runtime.server"];
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("StorageRuntimeServiceProvider requires application singleton().");
+    }
+
+    app.singleton(STORAGE_RUNTIME_SERVER_TOKEN, () => STORAGE_RUNTIME_SERVER_API);
+    app.singleton(KERNEL_TOKENS.Storage, (scope) => storageBinding.createStorageBinding(scope));
+  }
+
+  boot() {}
+}
+
+export { STORAGE_RUNTIME_SERVER_TOKEN, StorageRuntimeServiceProvider };

package/src/server/storageBinding.js

@@ -0,0 +1,57 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { createStorage } from "unstorage";
+import fsDriver from "unstorage/drivers/fs";
+import memoryDriver from "unstorage/drivers/memory";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+
+const STORAGE_DRIVER_ENV_KEY = "JSKIT_STORAGE_DRIVER";
+const STORAGE_FS_BASE_PATH_ENV_KEY = "JSKIT_STORAGE_FS_BASE_PATH";
+const DEFAULT_STORAGE_DRIVER = "fs";
+
+function normalizeStorageDriver(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized || DEFAULT_STORAGE_DRIVER;
+}
+
+function resolveFsBasePath(fsBasePath, { rootDir } = {}) {
+  const normalized = String(fsBasePath || "").trim();
+  if (normalized) {
+    return path.resolve(normalized);
+  }
+
+  const resolvedRootDir = rootDir || process.cwd();
+  return path.resolve(resolvedRootDir, "data", "storage");
+}
+
+function createStorageBinding(scope, { rootDir = process.cwd() } = {}) {
+  const env = scope && typeof scope.has === "function" && scope.has(KERNEL_TOKENS.Env) ? scope.make(KERNEL_TOKENS.Env) : {};
+  const driver = normalizeStorageDriver(env?.[STORAGE_DRIVER_ENV_KEY]);
+
+  if (driver === "memory") {
+    return createStorage({
+      driver: memoryDriver()
+    });
+  }
+
+  if (driver !== "fs") {
+    throw new Error(`Unsupported ${STORAGE_DRIVER_ENV_KEY} "${driver}". Supported: fs, memory.`);
+  }
+
+  const fsBasePath = resolveFsBasePath(env?.[STORAGE_FS_BASE_PATH_ENV_KEY], { rootDir });
+  mkdirSync(fsBasePath, { recursive: true });
+
+  return createStorage({
+    driver: fsDriver({
+      base: fsBasePath
+    })
+  });
+}
+
+export {
+  STORAGE_DRIVER_ENV_KEY,
+  STORAGE_FS_BASE_PATH_ENV_KEY,
+  DEFAULT_STORAGE_DRIVER,
+  normalizeStorageDriver,
+  createStorageBinding
+};

package/test/providerRuntime.test.js

@@ -0,0 +1,47 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { StorageRuntimeServiceProvider } from "../src/server/providers/StorageRuntimeServiceProvider.js";
+
+function createSingletonApp() {
+  const singletons = new Map();
+
+  return {
+    has(token) {
+      return singletons.has(token);
+    },
+    singleton(token, factory) {
+      singletons.set(token, factory(this));
+    },
+    make(token) {
+      if (!singletons.has(token)) {
+        throw new Error(`Token ${String(token)} is not registered.`);
+      }
+      return singletons.get(token);
+    }
+  };
+}
+
+test("StorageRuntimeServiceProvider registers runtime storage api and storage binding", async () => {
+  const app = createSingletonApp();
+  app.singleton(KERNEL_TOKENS.Env, () => ({
+    JSKIT_STORAGE_DRIVER: "memory"
+  }));
+
+  const provider = new StorageRuntimeServiceProvider();
+  provider.register(app);
+
+  assert.equal(app.has("runtime.storage"), true);
+  assert.equal(app.has(KERNEL_TOKENS.Storage), true);
+
+  const runtimeStorageApi = app.make("runtime.storage");
+  assert.equal(typeof runtimeStorageApi.createStorageBinding, "function");
+
+  const storage = app.make(KERNEL_TOKENS.Storage);
+  assert.equal(typeof storage.setItemRaw, "function");
+  assert.equal(typeof storage.getItemRaw, "function");
+
+  await storage.setItemRaw("tests/storage-runtime", Buffer.from("ok"));
+  const value = await storage.getItemRaw("tests/storage-runtime");
+  assert.equal(Buffer.from(value).toString(), "ok");
+});