@mushinjs/plugin-storage 0.0.0-stage → 0.2.0-next.20261112165327

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Setobox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { Context, Service, z } from "@mushinjs/core";
+declare module '@mushinjs/core' {
+  interface Context {
+    storage: Storage;
+  }
+}
+/**
+ * JSON documents under the data directory. A key such as `agent/abc` maps to `data/agent/abc.json`;
+ * logs use `.jsonl` files through `append` and `tail`.
+ */
+export declare class Storage extends Service {
+  static Config: z.ZodObject<{
+    dir: z.ZodDefault<z.ZodString>;
+  }, z.core.$strip>;
+  readonly dir: string;
+  constructor(ctx: Context, config: z.infer<typeof Storage.Config>);
+  private file;
+  get<T>(key: string): Promise<T | undefined>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Keys of the JSON documents directly under a prefix, such as `agent`. */
+  list(prefix: string): Promise<string[]>;
+  /** Appends one JSON line to `<key>.jsonl`. */
+  append(key: string, value: unknown): Promise<void>;
+  /** The last `limit` entries of `<key>.jsonl`, oldest first. */
+  tail<T>(key: string, limit: number): Promise<T[]>;
+  /** Path of a storage key relative to the data directory, for display. */
+  describe(key: string): string;
+}
+export { Storage as default };

package/dist/index.js

@@ -0,0 +1,68 @@
+import { appendFile, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { Service, field, readJson, writeJsonAtomic, z } from "@mushinjs/core";
+// src/index.ts
+const keyPattern = /^[A-Za-z0-9_-]+(\/[A-Za-z0-9_.-]+)*$/;
+/**
+* JSON documents under the data directory. A key such as `agent/abc` maps to `data/agent/abc.json`;
+* logs use `.jsonl` files through `append` and `tail`.
+*/
+var Storage = class extends Service {
+	static Config = z.object({ dir: z.string().default("data").meta(field("Data directory", "Relative to the instance directory", { "zh-CN": {
+		title: "数据目录",
+		description: "相对于实例目录"
+	} })) });
+	dir;
+	constructor(ctx, config) {
+		super(ctx, "storage");
+		this.dir = resolve(ctx.baseDir ?? process.cwd(), config.dir);
+	}
+	file(key, ext) {
+		if (!keyPattern.test(key) || key.split("/").includes("..")) throw new Error(`invalid storage key "${key}"`);
+		return join(this.dir, ...key.split("/")) + ext;
+	}
+	async get(key) {
+		return readJson(this.file(key, ".json"));
+	}
+	async set(key, value) {
+		return writeJsonAtomic(this.file(key, ".json"), value);
+	}
+	async delete(key) {
+		await rm(this.file(key, ".json"), { force: true });
+	}
+	/** Keys of the JSON documents directly under a prefix, such as `agent`. */
+	async list(prefix) {
+		const dir = join(this.dir, ...prefix.split("/"));
+		return (await readdir(dir).catch(() => [])).filter((name) => name.endsWith(".json")).map((name) => `${prefix}/${name.slice(0, -5)}`).sort();
+	}
+	/** Appends one JSON line to `<key>.jsonl`. */
+	async append(key, value) {
+		const file = this.file(key, ".jsonl");
+		await mkdir(dirname(file), { recursive: true });
+		await appendFile(file, JSON.stringify(value) + "\n", "utf8");
+	}
+	/** The last `limit` entries of `<key>.jsonl`, oldest first. */
+	async tail(key, limit) {
+		let text;
+		try {
+			text = await readFile(this.file(key, ".jsonl"), "utf8");
+		} catch (error) {
+			if (error?.code === "ENOENT") return [];
+			throw error;
+		}
+		return text.split("\n").filter(Boolean).slice(-limit).flatMap((line) => {
+			try {
+				return [JSON.parse(line)];
+			} catch {
+				return [];
+			}
+		});
+	}
+	/** Path of a storage key relative to the data directory, for display. */
+	describe(key) {
+		return relative(this.dir, this.file(key, ".json")).split(sep).join("/");
+	}
+};
+export { Storage, Storage as default };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { appendFile, mkdir, readdir, readFile, rm } from 'node:fs/promises'\r\nimport { dirname, join, relative, resolve, sep } from 'node:path'\r\nimport { Context, field, readJson, Service, writeJsonAtomic, z } from '@mushinjs/core'\r\n\r\ndeclare module '@mushinjs/core' {\r\n  interface Context {\r\n    storage: Storage\r\n  }\r\n}\r\n\r\nconst keyPattern = /^[A-Za-z0-9_-]+(\\/[A-Za-z0-9_.-]+)*$/\r\n\r\n/**\r\n * JSON documents under the data directory. A key such as `agent/abc` maps to `data/agent/abc.json`;\r\n * logs use `.jsonl` files through `append` and `tail`.\r\n */\r\nexport class Storage extends Service {\r\n  static Config = z.object({\r\n    dir: z.string().default('data').meta(field('Data directory', 'Relative to the instance directory', {\r\n      'zh-CN': { title: '数据目录', description: '相对于实例目录' },\r\n    })),\r\n  })\r\n\r\n  readonly dir: string\r\n\r\n  constructor(ctx: Context, config: z.infer<typeof Storage.Config>) {\r\n    super(ctx, 'storage')\r\n    this.dir = resolve(ctx.baseDir ?? process.cwd(), config.dir)\r\n  }\r\n\r\n  private file(key: string, ext: '.json' | '.jsonl') {\r\n    if (!keyPattern.test(key) || key.split('/').includes('..')) {\r\n      throw new Error(`invalid storage key \"${key}\"`)\r\n    }\r\n    return join(this.dir, ...key.split('/')) + ext\r\n  }\r\n\r\n  async get<T>(key: string): Promise<T | undefined> {\r\n    return readJson<T>(this.file(key, '.json'))\r\n  }\r\n\r\n  async set(key: string, value: unknown) {\r\n    return writeJsonAtomic(this.file(key, '.json'), value)\r\n  }\r\n\r\n  async delete(key: string) {\r\n    await rm(this.file(key, '.json'), { force: true })\r\n  }\r\n\r\n  /** Keys of the JSON documents directly under a prefix, such as `agent`. */\r\n  async list(prefix: string) {\r\n    const dir = join(this.dir, ...prefix.split('/'))\r\n    const names = await readdir(dir).catch(() => [] as string[])\r\n    return names\r\n      .filter((name) => name.endsWith('.json'))\r\n      .map((name) => `${prefix}/${name.slice(0, -'.json'.length)}`)\r\n      .sort()\r\n  }\r\n\r\n  /** Appends one JSON line to `<key>.jsonl`. */\r\n  async append(key: string, value: unknown) {\r\n    const file = this.file(key, '.jsonl')\r\n    await mkdir(dirname(file), { recursive: true })\r\n    await appendFile(file, JSON.stringify(value) + '\\n', 'utf8')\r\n  }\r\n\r\n  /** The last `limit` entries of `<key>.jsonl`, oldest first. */\r\n  async tail<T>(key: string, limit: number): Promise<T[]> {\r\n    let text: string\r\n    try {\r\n      text = await readFile(this.file(key, '.jsonl'), 'utf8')\r\n    } catch (error: any) {\r\n      if (error?.code === 'ENOENT') return []\r\n      throw error\r\n    }\r\n    const lines = text.split('\\n').filter(Boolean)\r\n    return lines.slice(-limit).flatMap((line) => {\r\n      try {\r\n        return [JSON.parse(line) as T]\r\n      } catch {\r\n        return []\r\n      }\r\n    })\r\n  }\r\n\r\n  /** Path of a storage key relative to the data directory, for display. */\r\n  describe(key: string) {\r\n    return relative(this.dir, this.file(key, '.json')).split(sep).join('/')\r\n  }\r\n}\r\n\r\nexport default Storage\r\n"],"mappings":";;;;AAUA,MAAM,aAAa;;;;;AAMnB,IAAa,UAAb,cAA6B,QAAQ;CACnC,OAAO,SAAS,EAAE,OAAO,EACvB,KAAK,EAAE,OAAO,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,KAAK,MAAM,kBAAkB,sCAAsC,EACjG,SAAS;EAAE,OAAO;EAAQ,aAAa;CAAU,EACnD,CAAC,CAAC,EACJ,CAAC;CAED;CAEA,YAAY,KAAc,QAAwC;EAChE,MAAM,KAAK,SAAS;EACpB,KAAK,MAAM,QAAQ,IAAI,WAAW,QAAQ,IAAI,GAAG,OAAO,GAAG;CAC7D;CAEA,KAAa,KAAa,KAAyB;EACjD,IAAI,CAAC,WAAW,KAAK,GAAG,KAAK,IAAI,MAAM,GAAG,CAAC,CAAC,SAAS,IAAI,GACvD,MAAM,IAAI,MAAM,wBAAwB,IAAI,EAAE;EAEhD,OAAO,KAAK,KAAK,KAAK,GAAG,IAAI,MAAM,GAAG,CAAC,IAAI;CAC7C;CAEA,MAAM,IAAO,KAAqC;EAChD,OAAO,SAAY,KAAK,KAAK,KAAK,OAAO,CAAC;CAC5C;CAEA,MAAM,IAAI,KAAa,OAAgB;EACrC,OAAO,gBAAgB,KAAK,KAAK,KAAK,OAAO,GAAG,KAAK;CACvD;CAEA,MAAM,OAAO,KAAa;EACxB,MAAM,GAAG,KAAK,KAAK,KAAK,OAAO,GAAG,EAAE,OAAO,KAAK,CAAC;CACnD;;CAGA,MAAM,KAAK,QAAgB;EACzB,MAAM,MAAM,KAAK,KAAK,KAAK,GAAG,OAAO,MAAM,GAAG,CAAC;EAE/C,QAAO,MADa,QAAQ,GAAG,CAAC,CAAC,YAAY,CAAC,CAAa,EAAA,CAExD,QAAQ,SAAS,KAAK,SAAS,OAAO,CAAC,CAAC,CACxC,KAAK,SAAS,GAAG,OAAO,GAAG,KAAK,MAAM,GAAG,EAAe,GAAG,CAAC,CAC5D,KAAK;CACV;;CAGA,MAAM,OAAO,KAAa,OAAgB;EACxC,MAAM,OAAO,KAAK,KAAK,KAAK,QAAQ;EACpC,MAAM,MAAM,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;EAC9C,MAAM,WAAW,MAAM,KAAK,UAAU,KAAK,IAAI,MAAM,MAAM;CAC7D;;CAGA,MAAM,KAAQ,KAAa,OAA6B;EACtD,IAAI;EACJ,IAAI;GACF,OAAO,MAAM,SAAS,KAAK,KAAK,KAAK,QAAQ,GAAG,MAAM;EACxD,SAAS,OAAY;GACnB,IAAI,OAAO,SAAS,UAAU,OAAO,CAAC;GACtC,MAAM;EACR;EAEA,OADc,KAAK,MAAM,IAAI,CAAC,CAAC,OAAO,OAC3B,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS;GAC3C,IAAI;IACF,OAAO,CAAC,KAAK,MAAM,IAAI,CAAM;GAC/B,QAAQ;IACN,OAAO,CAAC;GACV;EACF,CAAC;CACH;;CAGA,SAAS,KAAa;EACpB,OAAO,SAAS,KAAK,KAAK,KAAK,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG;CACxE;AACF"}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@mushinjs/plugin-storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-next.20261112165327",
+  "description": "JSON document storage",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mushinjs/mushin.git",
+    "directory": "packages/plugin-storage"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mushin-plugin"
+  ],
+  "mushin": {
+    "kind": "app",
+    "essential": true,
+    "displayName": {
+      "en": "Storage",
+      "zh-CN": "存储"
+    },
+    "description": {
+      "en": "Stores providers, bots and sessions as JSON files",
+      "zh-CN": "以 JSON 文件保存提供商、机器人与会话"
+    },
+    "provides": [
+      "storage"
+    ]
+  },
+  "dependencies": {
+    "@mushinjs/core": "0.2.0-next.20261112165327"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.