@guanghechen/config 2.0.0 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present guanghechen (https://github.com/guanghechen)
+
+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/README.md

@@ -49,7 +49,9 @@
 </header>
 <br/>
 
-Utilities for defining config followed by semantic version.
+Utilities for defining versioned configuration with integrity verification. Provides base classes
+for managing configuration data with semantic versioning compatibility checks, MAC (Message
+Authentication Code) validation, and resource-based persistence.
 
 ## Install
 
@@ -67,5 +69,113 @@ Utilities for defining config followed by semantic version.
 
 ## Usage
 
+### Using PlainJsonConfigKeeper
+
+For simple JSON configurations without custom serialization:
+
+```typescript
+import { PlainJsonConfigKeeper } from '@guanghechen/config'
+import type { ITextResource } from '@guanghechen/types'
+
+interface IAppConfig {
+  theme: 'light' | 'dark'
+  language: string
+  autoSave: boolean
+}
+
+// Create a text resource (e.g., file-based)
+const resource: ITextResource = {
+  load: async () => { /* read from file */ },
+  save: async (content: string) => { /* write to file */ },
+  destroy: async () => { /* cleanup */ },
+}
+
+const keeper = new PlainJsonConfigKeeper<IAppConfig>({ resource })
+
+// Load existing config
+const config = await keeper.load()
+console.log(config.theme) // 'light'
+
+// Update and save
+await keeper.update({ ...config, theme: 'dark' })
+await keeper.save()
+```
+
+### Creating Custom ConfigKeeper
+
+For configurations requiring custom serialization/deserialization:
+
+```typescript
+import { JsonConfigKeeper } from '@guanghechen/config'
+import type { ITextResource } from '@guanghechen/types'
+
+// Runtime instance type
+interface IUserSettings {
+  username: string
+  createdAt: Date
+  preferences: Map<string, string>
+}
+
+// Serializable data type (JSON-compatible)
+interface IUserSettingsData {
+  username: string
+  createdAt: string // ISO date string
+  preferences: Array<[string, string]>
+}
+
+class UserSettingsKeeper extends JsonConfigKeeper<IUserSettings, IUserSettingsData> {
+  public readonly __version__ = '1.0.0'
+  public readonly __compatible_version__ = '~1.0.0' // semver range
+
+  protected async serialize(instance: IUserSettings): Promise<IUserSettingsData> {
+    return {
+      username: instance.username,
+      createdAt: instance.createdAt.toISOString(),
+      preferences: Array.from(instance.preferences.entries()),
+    }
+  }
+
+  protected async deserialize(data: IUserSettingsData): Promise<IUserSettings> {
+    return {
+      username: data.username,
+      createdAt: new Date(data.createdAt),
+      preferences: new Map(data.preferences),
+    }
+  }
+}
+
+const keeper = new UserSettingsKeeper({ resource })
+
+// Load, modify, save
+const settings = await keeper.load()
+settings.preferences.set('fontSize', '14px')
+await keeper.update(settings)
+await keeper.save()
+```
+
+### Version Compatibility
+
+The config keeper enforces version compatibility using semantic versioning:
+
+```typescript
+class MyConfigKeeper extends JsonConfigKeeper<MyInstance, MyData> {
+  public readonly __version__ = '2.1.0'
+  public readonly __compatible_version__ = '^2.0.0' // accepts 2.x.x
+
+  // ... serialize/deserialize implementations
+}
+
+const keeper = new MyConfigKeeper({ resource })
+
+// Check version compatibility manually
+if (keeper.compatible('2.0.5')) {
+  console.log('Version is compatible')
+}
+```
+
+## Reference
+
+- [homepage][homepage]
+
 [homepage]:
-  https://github.com/guanghechen/sora/tree/@guanghechen/config@2.0.0/packages/config#readme
+  https://github.com/guanghechen/sora/tree/@guanghechen/config@2.0.0/packages/config#readme

package/lib/cjs/index.cjs

@@ -4,7 +4,6 @@ var byte = require('@guanghechen/byte');
 var invariant = require('@guanghechen/invariant');
 var version = require('@guanghechen/version');
 var node_crypto = require('node:crypto');
-var config_types = require('@guanghechen/config.types');
 
 function calcMac(chunks, algorithm) {
     const hash = node_crypto.createHash(algorithm);
@@ -108,9 +107,3 @@ class PlainJsonConfigKeeper extends JsonConfigKeeper {
 exports.BaseConfigKeeper = BaseConfigKeeper;
 exports.JsonConfigKeeper = JsonConfigKeeper;
 exports.PlainJsonConfigKeeper = PlainJsonConfigKeeper;
-Object.keys(config_types).forEach(function (k) {
-    if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
-        enumerable: true,
-        get: function () { return config_types[k]; }
-    });
-});

package/lib/esm/index.mjs

@@ -2,7 +2,6 @@ import { bytes2text, randomBytes, text2bytes } from '@guanghechen/byte';
 import { invariant } from '@guanghechen/invariant';
 import { satisfies } from '@guanghechen/version';
 import { createHash } from 'node:crypto';
-export * from '@guanghechen/config.types';
 
 function calcMac(chunks, algorithm) {
     const hash = createHash(algorithm);

package/lib/types/index.d.ts

@@ -1,9 +1,61 @@
-import { IConfigKeeper, IConfig } from '@guanghechen/config.types';
-export * from '@guanghechen/config.types';
-import { ITextResource } from '@guanghechen/resource';
+import { ITextResource } from '@guanghechen/types';
 
 type IHashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha512';
 
+interface IConfig<Data> {
+    /**
+     * Config version.
+     */
+    __version__: string;
+    /**
+     * Mac of data.
+     */
+    __mac__: string;
+    /**
+     * A random string.
+     */
+    __nonce__: string | undefined;
+    /**
+     * Payload data.
+     */
+    data: Data;
+}
+interface IConfigKeeper<D> {
+    readonly __version__: string;
+    readonly __compatible_version__: string;
+    /**
+     * Current holding data.
+     */
+    readonly data: Readonly<D> | undefined;
+    /**
+     * Check if the given version is compatible.
+     * @param version
+     */
+    compatible(version: string): boolean;
+    /**
+     * Remove the config data.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Load data from the given resource or default resource, this will update the holding data.
+     */
+    load(resource?: ITextResource): Promise<D | never>;
+    /**
+     * Parse the data from the given config content, this won't update the holding data.
+     * @param configContent
+     */
+    parse(configContent: string): Promise<D | never>;
+    /**
+     * Save current holding data into the given resource or default resource.
+     */
+    save(resource?: ITextResource): Promise<void>;
+    /**
+     * Update the holding data.
+     * @param data
+     */
+    update(data: D): Promise<void>;
+}
+
 interface IBaseConfigKeeperProps {
     /**
      * The resource which hold the config data.
@@ -54,4 +106,4 @@ declare class PlainJsonConfigKeeper<Data> extends JsonConfigKeeper<Data, Data> i
 }
 
 export { BaseConfigKeeper, JsonConfigKeeper, PlainJsonConfigKeeper };
-export type { IBaseConfigKeeperProps, IJsonConfigKeeperProps };
+export type { IBaseConfigKeeperProps, IConfig, IConfigKeeper, IJsonConfigKeeperProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/config",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "author": {
     "name": "guanghechen",
     "url": "https://github.com/guanghechen/"
@@ -8,17 +8,17 @@
   "description": "Utilities for defining config followed by semantic version.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/config@1.0.5",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/config@2.0.0",
     "directory": "packages/config"
   },
-  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/config@1.0.5/packages/config#readme",
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/config@2.0.0/packages/config#readme",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./lib/types/index.d.ts",
       "source": "./src/index.ts",
       "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.cjs",
-      "types": "./lib/types/index.d.ts"
+      "require": "./lib/cjs/index.cjs"
     }
   },
   "source": "./src/index.ts",
@@ -26,13 +26,6 @@
   "module": "./lib/esm/index.mjs",
   "types": "./lib/types/index.d.ts",
   "license": "MIT",
-  "scripts": {
-    "build": "rollup -c ../../rollup.config.mjs",
-    "clean": "rimraf lib",
-    "test": "vitest run --config ../../vitest.config.ts",
-    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
-    "test:update": "vitest run --config ../../vitest.config.ts -u"
-  },
   "files": [
     "lib/",
     "!lib/**/*.map",
@@ -42,11 +35,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@guanghechen/byte": "^2.0.0",
-    "@guanghechen/config.types": "^2.0.0",
-    "@guanghechen/invariant": "^7.0.0",
-    "@guanghechen/resource": "^2.0.0",
-    "@guanghechen/version": "^1.0.0"
+    "@guanghechen/byte": "^2.0.1",
+    "@guanghechen/invariant": "^7.0.1",
+    "@guanghechen/types": "^2.0.1",
+    "@guanghechen/version": "^1.0.1"
   },
-  "gitHead": "12990a720b31d50d217e2e17a6191256dc94eda6"
-}
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.mjs",
+    "clean": "rimraf lib",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
+    "test:update": "vitest run --config ../../vitest.config.ts -u"
+  }
+}