@tikkhun/version 2025.7.7 → 2026.4.13

package/dist/lib/VersionUpdateResult.d.mts

@@ -1,28 +1,40 @@
-interface SuccessOptions {
-    message: string;
-    oldVersion?: string;
-    newVersion: string;
-}
-interface ErrorOptions {
-    oldVersion: string;
-    newVersion?: string;
-    message: string;
+import { StoreResult, VersionValue, StoreGetResult, StoreSetResult } from './store/Store.mjs';
+
+/**
+ * @description store 聚合结果.
+ */
+interface VersionManagerResult<T extends StoreResult = StoreResult> {
+    /**
+     * @description 当前操作是否全部成功.
+     */
+    success: boolean;
+    /**
+     * @description 本次操作处理的版本值.
+     */
+    value?: VersionValue;
+    /**
+     * @description 每个 store 的执行结果.
+     */
+    results: T[];
 }
+/**
+ * @description 读取聚合结果.
+ */
+type VersionReadResult = VersionManagerResult<StoreGetResult>;
+/**
+ * @description 写入聚合结果.
+ */
+type VersionSetResult = VersionManagerResult<StoreSetResult>;
+/**
+ * @description 结果工厂.
+ */
 declare class VersionUpdateResult {
-    static success(opts: SuccessOptions): {
-        message: string;
-        oldVersion?: string;
-        newVersion: string;
-        isSuccess: boolean;
-        isError: boolean;
-    };
-    static error(opts: ErrorOptions): {
-        oldVersion: string;
-        newVersion?: string;
-        message: string;
-        isSuccess: boolean;
-        isError: boolean;
-    };
+    /**
+     * @description 聚合多个 store 结果.
+     * @param results store 结果列表.
+     * @param value 当前版本值.
+     */
+    static create<T extends StoreResult>(results: T[], value?: VersionValue): VersionManagerResult<T>;
 }
 
-export { type ErrorOptions, type SuccessOptions, VersionUpdateResult };
+export { type VersionManagerResult, type VersionReadResult, type VersionSetResult, VersionUpdateResult };

package/dist/lib/VersionUpdateResult.d.ts

@@ -1,28 +1,40 @@
-interface SuccessOptions {
-    message: string;
-    oldVersion?: string;
-    newVersion: string;
-}
-interface ErrorOptions {
-    oldVersion: string;
-    newVersion?: string;
-    message: string;
+import { StoreResult, VersionValue, StoreGetResult, StoreSetResult } from './store/Store.js';
+
+/**
+ * @description store 聚合结果.
+ */
+interface VersionManagerResult<T extends StoreResult = StoreResult> {
+    /**
+     * @description 当前操作是否全部成功.
+     */
+    success: boolean;
+    /**
+     * @description 本次操作处理的版本值.
+     */
+    value?: VersionValue;
+    /**
+     * @description 每个 store 的执行结果.
+     */
+    results: T[];
 }
+/**
+ * @description 读取聚合结果.
+ */
+type VersionReadResult = VersionManagerResult<StoreGetResult>;
+/**
+ * @description 写入聚合结果.
+ */
+type VersionSetResult = VersionManagerResult<StoreSetResult>;
+/**
+ * @description 结果工厂.
+ */
 declare class VersionUpdateResult {
-    static success(opts: SuccessOptions): {
-        message: string;
-        oldVersion?: string;
-        newVersion: string;
-        isSuccess: boolean;
-        isError: boolean;
-    };
-    static error(opts: ErrorOptions): {
-        oldVersion: string;
-        newVersion?: string;
-        message: string;
-        isSuccess: boolean;
-        isError: boolean;
-    };
+    /**
+     * @description 聚合多个 store 结果.
+     * @param results store 结果列表.
+     * @param value 当前版本值.
+     */
+    static create<T extends StoreResult>(results: T[], value?: VersionValue): VersionManagerResult<T>;
 }
 
-export { type ErrorOptions, type SuccessOptions, VersionUpdateResult };
+export { type VersionManagerResult, type VersionReadResult, type VersionSetResult, VersionUpdateResult };

package/dist/lib/VersionUpdateResult.js

@@ -1,5 +1,5 @@
 'use strict';/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
-var c=Object.defineProperty;var t=Object.getOwnPropertySymbols;var a=Object.prototype.hasOwnProperty,g=Object.prototype.propertyIsEnumerable;var n=(e,s,r)=>s in e?c(e,s,{enumerable:true,configurable:true,writable:true,value:r}):e[s]=r,i=(e,s)=>{for(var r in s||(s={}))a.call(s,r)&&n(e,r,s[r]);if(t)for(var r of t(s))g.call(s,r)&&n(e,r,s[r]);return e};var o=class{static success(s){return i({isSuccess:true,isError:false},s)}static error(s){return i({isSuccess:false,isError:true},s)}};exports.VersionUpdateResult=o;
+var t=class{static create(e,s){return {success:e.every(r=>r.success),value:s,results:e}}};exports.VersionUpdateResult=t;

package/dist/lib/VersionUpdateResult.mjs

@@ -1,5 +1,5 @@
 /**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
-var c=Object.defineProperty;var t=Object.getOwnPropertySymbols;var a=Object.prototype.hasOwnProperty,g=Object.prototype.propertyIsEnumerable;var n=(e,s,r)=>s in e?c(e,s,{enumerable:true,configurable:true,writable:true,value:r}):e[s]=r,i=(e,s)=>{for(var r in s||(s={}))a.call(s,r)&&n(e,r,s[r]);if(t)for(var r of t(s))g.call(s,r)&&n(e,r,s[r]);return e};var o=class{static success(s){return i({isSuccess:true,isError:false},s)}static error(s){return i({isSuccess:false,isError:true},s)}};export{o as VersionUpdateResult};
+var t=class{static create(e,s){return {success:e.every(r=>r.success),value:s,results:e}}};export{t as VersionUpdateResult};

package/dist/lib/getter/NodeVersionGetter.js

@@ -1,5 +1,5 @@
 'use strict';var utils=require('@tikkhun/utils');/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
 var r=class{get(){return utils.currentNodeVersion}};exports.NodeVersionGetter=r;

package/dist/lib/getter/NodeVersionGetter.mjs

@@ -1,5 +1,5 @@
 import {currentNodeVersion}from'@tikkhun/utils';/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
 var r=class{get(){return currentNodeVersion}};export{r as NodeVersionGetter};

package/dist/lib/getter/SemanticVersionGetter.js

@@ -1,5 +1,5 @@
 'use strict';var fsExtra=require('fs-extra');/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
 var a=(p,r,e)=>new Promise((t,i)=>{var f=o=>{try{n(e.next(o));}catch(s){i(s);}},c=o=>{try{n(e.throw(o));}catch(s){i(s);}},n=o=>o.done?t(o.value):Promise.resolve(o.value).then(f,c);n((e=e.apply(p,r)).next());});var u=(t=>(t[t.major=0]="major",t[t.minor=1]="minor",t[t.patch=2]="patch",t))(u||{}),g={file:"package.json",position:2,key:"version"},m=class{constructor(r){this.opts=Object.assign({},g,r);}get(){return a(this,null,function*(){if(!(yield fsExtra.pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:r}=yield fsExtra.readJson(this.opts.file);if(!r)throw new Error("get new version, but error: the old version is not found");if(typeof r!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(r)}`);let[e,t,i]=r.split(".");return this.opts.position===0?[Number(e)+1,t,i].join("."):this.opts.position===1?[e,Number(t)+1,i].join("."):[e,t,Number(i)+1].join(".")})}};exports.DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS=g;exports.Positions=u;exports.SemanticVersionGetter=m;

package/dist/lib/getter/SemanticVersionGetter.mjs

@@ -1,5 +1,5 @@
 import {pathExists,readJson}from'fs-extra';/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
 var a=(p,r,e)=>new Promise((t,i)=>{var f=o=>{try{n(e.next(o));}catch(s){i(s);}},c=o=>{try{n(e.throw(o));}catch(s){i(s);}},n=o=>o.done?t(o.value):Promise.resolve(o.value).then(f,c);n((e=e.apply(p,r)).next());});var u=(t=>(t[t.major=0]="major",t[t.minor=1]="minor",t[t.patch=2]="patch",t))(u||{}),g={file:"package.json",position:2,key:"version"},m=class{constructor(r){this.opts=Object.assign({},g,r);}get(){return a(this,null,function*(){if(!(yield pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:r}=yield readJson(this.opts.file);if(!r)throw new Error("get new version, but error: the old version is not found");if(typeof r!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(r)}`);let[e,t,i]=r.split(".");return this.opts.position===0?[Number(e)+1,t,i].join("."):this.opts.position===1?[e,Number(t)+1,i].join("."):[e,t,Number(i)+1].join(".")})}};export{g as DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS,u as Positions,m as SemanticVersionGetter};

package/dist/lib/getter/index.js

@@ -1,5 +1,5 @@
 'use strict';var utils=require('@tikkhun/utils'),fsExtra=require('fs-extra');/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
 var m=(n,r,e)=>new Promise((t,i)=>{var c=o=>{try{s(e.next(o));}catch(p){i(p);}},h=o=>{try{s(e.throw(o));}catch(p){i(p);}},s=o=>o.done?t(o.value):Promise.resolve(o.value).then(c,h);s((e=e.apply(n,r)).next());});var a=class{get(){return utils.currentNodeVersion}};var w=(t=>(t[t.major=0]="major",t[t.minor=1]="minor",t[t.patch=2]="patch",t))(w||{}),x={file:"package.json",position:2,key:"version"},f=class{constructor(r){this.opts=Object.assign({},x,r);}get(){return m(this,null,function*(){if(!(yield fsExtra.pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:r}=yield fsExtra.readJson(this.opts.file);if(!r)throw new Error("get new version, but error: the old version is not found");if(typeof r!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(r)}`);let[e,t,i]=r.split(".");return this.opts.position===0?[Number(e)+1,t,i].join("."):this.opts.position===1?[e,Number(t)+1,i].join("."):[e,t,Number(i)+1].join(".")})}};exports.DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS=x;exports.NodeVersionGetter=a;exports.Positions=w;exports.SemanticVersionGetter=f;

package/dist/lib/getter/index.mjs

@@ -1,5 +1,5 @@
 import {currentNodeVersion}from'@tikkhun/utils';import {pathExists,readJson}from'fs-extra';/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
 var m=(n,r,e)=>new Promise((t,i)=>{var c=o=>{try{s(e.next(o));}catch(p){i(p);}},h=o=>{try{s(e.throw(o));}catch(p){i(p);}},s=o=>o.done?t(o.value):Promise.resolve(o.value).then(c,h);s((e=e.apply(n,r)).next());});var a=class{get(){return currentNodeVersion}};var w=(t=>(t[t.major=0]="major",t[t.minor=1]="minor",t[t.patch=2]="patch",t))(w||{}),x={file:"package.json",position:2,key:"version"},f=class{constructor(r){this.opts=Object.assign({},x,r);}get(){return m(this,null,function*(){if(!(yield pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:r}=yield readJson(this.opts.file);if(!r)throw new Error("get new version, but error: the old version is not found");if(typeof r!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(r)}`);let[e,t,i]=r.split(".");return this.opts.position===0?[Number(e)+1,t,i].join("."):this.opts.position===1?[e,Number(t)+1,i].join("."):[e,t,Number(i)+1].join(".")})}};export{x as DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS,a as NodeVersionGetter,w as Positions,f as SemanticVersionGetter};

package/dist/lib/index.d.mts

@@ -1,7 +1,10 @@
 export { DEFAULT_VERSION_MANAGER_OPTIONS, VersionManager, VersionManagerOptions } from './VersionManager.mjs';
+export { VersionManagerResult, VersionReadResult, VersionSetResult, VersionUpdateResult } from './VersionUpdateResult.mjs';
 export { workspace } from './utils.mjs';
+export { ConfigStore } from './store/ConfigStore.mjs';
 export { DEFAULT_JSON_STORE_OPTIONS, JsonStore, JsonStoreOptions } from './store/JsonStore.mjs';
-export { Store, StoreOptions } from './store/Store.mjs';
+export { BaseVersionTarget, CustomVersionTarget, Store, StoreGetResult, StoreResult, StoreSetResult, StructuredVersionTarget, StructuredVersionTargetType, TextStoreMode, TextVersionTarget, VersionTarget, VersionValue } from './store/Store.mjs';
+export { StoreFactory } from './store/StoreFactory.mjs';
 export { DEFAULT_TEXT_STORE_OPTIONS, TextStore, TextStoreOptions } from './store/TextStore.mjs';
 export { NodeVersionGetter } from './getter/NodeVersionGetter.mjs';
 export { DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS, Positions, SemanticVersionGetter, SemanticVersionGetterOptions } from './getter/SemanticVersionGetter.mjs';

package/dist/lib/index.d.ts

@@ -1,7 +1,10 @@
 export { DEFAULT_VERSION_MANAGER_OPTIONS, VersionManager, VersionManagerOptions } from './VersionManager.js';
+export { VersionManagerResult, VersionReadResult, VersionSetResult, VersionUpdateResult } from './VersionUpdateResult.js';
 export { workspace } from './utils.js';
+export { ConfigStore } from './store/ConfigStore.js';
 export { DEFAULT_JSON_STORE_OPTIONS, JsonStore, JsonStoreOptions } from './store/JsonStore.js';
-export { Store, StoreOptions } from './store/Store.js';
+export { BaseVersionTarget, CustomVersionTarget, Store, StoreGetResult, StoreResult, StoreSetResult, StructuredVersionTarget, StructuredVersionTargetType, TextStoreMode, TextVersionTarget, VersionTarget, VersionValue } from './store/Store.js';
+export { StoreFactory } from './store/StoreFactory.js';
 export { DEFAULT_TEXT_STORE_OPTIONS, TextStore, TextStoreOptions } from './store/TextStore.js';
 export { NodeVersionGetter } from './getter/NodeVersionGetter.js';
 export { DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS, Positions, SemanticVersionGetter, SemanticVersionGetterOptions } from './getter/SemanticVersionGetter.js';

package/dist/lib/index.js

@@ -1,5 +1,6 @@
-'use strict';var logger=require('@tikkhun/logger'),fsExtra=require('fs-extra'),k=require('fs'),v=require('path'),dateVersion=require('@tikkhun/date-version'),utils=require('@tikkhun/utils');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var k__default=/*#__PURE__*/_interopDefault(k);var v__default=/*#__PURE__*/_interopDefault(v);/**
+'use strict';var logger=require('@tikkhun/logger'),fsExtra=require('fs-extra'),fastXmlParser=require('fast-xml-parser'),R=require('js-yaml'),lodash=require('lodash'),smolToml=require('smol-toml'),dateVersion=require('@tikkhun/date-version'),utils=require('@tikkhun/utils');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var R__default=/*#__PURE__*/_interopDefault(R);/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
-var E=Object.defineProperty,T=Object.defineProperties;var d=Object.getOwnPropertyDescriptors;var m=Object.getOwnPropertySymbols;var N=Object.prototype.hasOwnProperty,_=Object.prototype.propertyIsEnumerable;var c=(e,t,r)=>t in e?E(e,t,{enumerable:true,configurable:true,writable:true,value:r}):e[t]=r,l=(e,t)=>{for(var r in t||(t={}))N.call(t,r)&&c(e,r,t[r]);if(m)for(var r of m(t))_.call(t,r)&&c(e,r,t[r]);return e},g=(e,t)=>T(e,d(t));var n=(e,t,r)=>new Promise((o,s)=>{var w=i=>{try{a(r.next(i));}catch(f){s(f);}},y=i=>{try{a(r.throw(i));}catch(f){s(f);}},a=i=>i.done?o(i.value):Promise.resolve(i.value).then(w,y);a((r=r.apply(e,t)).next());});var V={file:"package.json",key:"version"},p=class{constructor(t){this.opts=Object.assign({},V,t);}update(t){return n(this,null,function*(){try{let r=yield fsExtra.readJson(this.opts.file);return yield fsExtra.writeJson(this.opts.file,g(l({},r),{[this.opts.key]:t}),{spaces:2}),!0}catch(r){return  false}})}};var h=process.cwd();var B={file:""},u=class{constructor(t){this.opts=t,this.filePath=v__default.default.join(h,this.opts.file);}update(t){try{return typeof t!="string"&&(t=JSON.stringify(t)),k__default.default.writeFileSync(this.filePath,t,"utf8"),!0}catch(r){return  false}}};var A={getter:{get(){return dateVersion.getDateVersion()}},store:new p},O=class{constructor(t){this.logger=new logger.Logger("VersionManager");this.opts=Object.assign({},A,t);}get(){return this.opts.getter.get()}update(){return n(this,null,function*(){let t=yield this.get();this.logger.log("new version: "+t);let r=Array.isArray(this.opts.store)?this.opts.store:[this.opts.store];try{if((yield Promise.all(r.map(s=>s.update(t)))).filter(s=>!s).length)throw new Error("update, but error");return !0}catch(o){return  false}})}};var S=class{get(){return utils.currentNodeVersion}};var R=(o=>(o[o.major=0]="major",o[o.minor=1]="minor",o[o.patch=2]="patch",o))(R||{}),D={file:"package.json",position:2,key:"version"},x=class{constructor(t){this.opts=Object.assign({},D,t);}get(){return n(this,null,function*(){if(!(yield fsExtra.pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:t}=yield fsExtra.readJson(this.opts.file);if(!t)throw new Error("get new version, but error: the old version is not found");if(typeof t!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(t)}`);let[r,o,s]=t.split(".");return this.opts.position===0?[Number(r)+1,o,s].join("."):this.opts.position===1?[r,Number(o)+1,s].join("."):[r,o,Number(s)+1].join(".")})}};exports.DEFAULT_JSON_STORE_OPTIONS=V;exports.DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS=D;exports.DEFAULT_TEXT_STORE_OPTIONS=B;exports.DEFAULT_VERSION_MANAGER_OPTIONS=A;exports.JsonStore=p;exports.NodeVersionGetter=S;exports.Positions=R;exports.SemanticVersionGetter=x;exports.TextStore=u;exports.VersionManager=O;exports.workspace=h;
+var b=Object.defineProperty,j=Object.defineProperties;var A=Object.getOwnPropertyDescriptors;var V=Object.getOwnPropertySymbols;var M=Object.prototype.hasOwnProperty,k=Object.prototype.propertyIsEnumerable;var E=(n,t,e)=>t in n?b(n,t,{enumerable:true,configurable:true,writable:true,value:e}):n[t]=e,u=(n,t)=>{for(var e in t||(t={}))M.call(t,e)&&E(n,e,t[e]);if(V)for(var e of V(t))k.call(t,e)&&E(n,e,t[e]);return n},p=(n,t)=>j(n,A(t));var o=(n,t,e)=>new Promise((r,s)=>{var i=a=>{try{g(e.next(a));}catch(S){s(S);}},c=a=>{try{g(e.throw(a));}catch(S){s(S);}},g=a=>a.done?r(a.value):Promise.resolve(a.value).then(i,c);g((e=e.apply(n,t)).next());});var l=class{constructor(t){this.target=t;}get(){return o(this,null,function*(){var t;try{if(!(yield fsExtra.pathExists(this.target.file)))return this.createGetError(`file is not found: ${this.target.file}`);let e=yield this.loadStructuredConfig(),r=this.target.path?lodash.get(e,this.target.path):e;return r===void 0?this.createGetError(`path is not found: ${(t=this.target.path)!=null?t:"<root>"}`):typeof r!="string"&&typeof r!="number"?this.createGetError(`value is not string or number: ${JSON.stringify(r)}`):{action:"get",success:!0,file:this.target.file,type:this.target.type,value:r}}catch(e){return this.createGetError(this.getErrorMessage(e))}})}set(t){return o(this,null,function*(){try{let e=yield this.get(),r=e.success?e.value:void 0,s=yield fsExtra.pathExists(this.target.file);if(!s){if(!this.target.createIfNotExists)return this.createSetError(t,`file is not found: ${this.target.file}`,r,"set");yield fsExtra.ensureFile(this.target.file);}let i=s?yield this.loadStructuredConfig():{};if(this.target.path)lodash.set(i,this.target.path,t),yield this.saveStructuredConfig(i);else {if(typeof i=="object"&&i!==null&&!Array.isArray(i))return this.createSetError(t,"path is required for structured target",r,"set");yield this.saveStructuredConfig(t);}return {action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:r,newValue:t}}catch(e){return this.createSetError(t,this.getErrorMessage(e),void 0,"set")}})}update(t){return o(this,null,function*(){let e=yield this.set(t);return p(u({},e),{action:"update"})})}createGetError(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t}}createSetError(t,e,r,s="set"){return {action:s,success:false,file:this.target.file,type:this.target.type,oldValue:r,newValue:t,message:e}}getErrorMessage(t){return t instanceof Error?t.message:String(t)}loadStructuredConfig(){return o(this,null,function*(){var e;let t=yield fsExtra.readFile(this.target.file,(e=this.target.encoding)!=null?e:"utf8");switch(this.target.type){case "json":return JSON.parse(t);case "yaml":return R__default.default.load(t);case "toml":return smolToml.parse(t);case "xml":return new fastXmlParser.XMLParser({ignoreAttributes:true}).parse(t);case "env":return this.parseEnvContent(t);default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}saveStructuredConfig(t){return o(this,null,function*(){var r;let e=(r=this.target.encoding)!=null?r:"utf8";switch(this.target.type){case "json":yield fsExtra.writeFile(this.target.file,JSON.stringify(t,null,2),e);return;case "yaml":yield fsExtra.writeFile(this.target.file,R__default.default.dump(t),e);return;case "toml":yield fsExtra.writeFile(this.target.file,smolToml.stringify(t),e);return;case "xml":yield fsExtra.writeFile(this.target.file,new fastXmlParser.XMLBuilder({format:true,ignoreAttributes:true}).build(t),e);return;case "env":yield fsExtra.writeFile(this.target.file,this.stringifyEnvContent(t),e);return;default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}parseEnvContent(t){let e={},r=t.split(/\r?\n/);for(let s of r){let i=s.trim();if(!i||i.startsWith("#"))continue;let c=i.indexOf("=");if(c<0)continue;let g=i.slice(0,c).trim(),a=i.slice(c+1).trim();lodash.set(e,g.replace(/__/g,"."),a);}return e}stringifyEnvContent(t){let e=[],r=(s,i)=>{if(s!==null&&typeof s=="object"&&!Array.isArray(s)){for(let[g,a]of Object.entries(s))r(a,[...i,g]);return}let c=i.join("__").toUpperCase();e.push(`${c}=${s!=null?s:""}`);};for(let[s,i]of Object.entries(t))r(i,[s]);return e.join(`
+`)}};var D={file:"package.json",key:"version"},m=class extends l{constructor(t){var s;let e=Object.assign({},D,t),r={type:"json",file:e.file,path:(s=e.path)!=null?s:e.key,createIfNotExists:e.createIfNotExists};super(r);}};var X={file:"",mode:"raw",trim:true,replacement:"{{version}}"},d=class{constructor(t){this.target=u(u({type:"text"},X),t);}get(){return o(this,null,function*(){var t;try{if(!(yield fsExtra.pathExists(this.target.file)))return this.createGetError(`file is not found: ${this.target.file}`);let e=yield fsExtra.readFile(this.target.file,(t=this.target.encoding)!=null?t:"utf8"),r=this.resolveValueFromText(e);return r===void 0?this.createGetError("version is not found in text content"):{action:"get",success:!0,file:this.target.file,type:this.target.type,value:r}}catch(e){return this.createGetError(this.getErrorMessage(e))}})}set(t){return o(this,null,function*(){try{let e=yield this.get(),r=e.success?e.value:void 0,s=yield this.createNextText(t);return yield this.writeText(s),{action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:r,newValue:t}}catch(e){return {action:"set",success:false,file:this.target.file,type:this.target.type,newValue:t,message:this.getErrorMessage(e)}}})}update(t){return o(this,null,function*(){let e=yield this.set(t);return p(u({},e),{action:"update"})})}resolveValueFromText(t){var e;if(this.target.mode==="replace"){let s=this.createPattern().exec(t);if(!s)return;let i=(e=s.groups)==null?void 0:e.version;return i!==void 0?i:s[1]!==void 0?s[1]:s[0]}return this.target.trim?t.trim():t}createNextText(t){return o(this,null,function*(){var e,r;if(this.target.mode==="replace"){if(!(yield fsExtra.pathExists(this.target.file)))throw new Error(`file is not found: ${this.target.file}`);let s=yield fsExtra.readFile(this.target.file,(e=this.target.encoding)!=null?e:"utf8");if(!this.createPattern().test(s))throw new Error("pattern is not matched");let c=((r=this.target.replacement)!=null?r:"{{version}}").replaceAll("{{version}}",String(t));return s.replace(this.createPattern(),c)}return String(t)})}writeText(t){return o(this,null,function*(){var e;if(!(yield fsExtra.pathExists(this.target.file))){if(!this.target.createIfNotExists)throw new Error(`file is not found: ${this.target.file}`);yield fsExtra.ensureFile(this.target.file);}yield fsExtra.writeFile(this.target.file,t,(e=this.target.encoding)!=null?e:"utf8");})}createPattern(){if(!this.target.pattern)throw new Error("pattern is required when text mode is replace");return new RegExp(this.target.pattern,this.target.flags)}createGetError(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t}}getErrorMessage(t){return t instanceof Error?t.message:String(t)}};var y=class{static create(t){return t.type==="text"?new d(t):t.type==="custom"?new x(t):new l(t)}},x=class{constructor(t){this.target=t;}get(){return o(this,null,function*(){if(!this.target.get)return {action:"get",success:false,file:this.target.file,type:this.target.type,message:"custom get is not implemented"};try{let t=yield this.target.get(this.target.file);return {action:"get",success:!0,file:this.target.file,type:this.target.type,value:t}}catch(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t instanceof Error?t.message:String(t)}}})}set(t){return o(this,null,function*(){try{let e=yield this.get();return this.target.set?(yield this.target.set(t,this.target.file),{action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:e.success?e.value:void 0,newValue:t}):{action:"set",success:!1,file:this.target.file,type:this.target.type,oldValue:e.success?e.value:void 0,newValue:t,message:"custom set is not implemented"}}catch(e){return {action:"set",success:false,file:this.target.file,type:this.target.type,newValue:t,message:e instanceof Error?e.message:String(e)}}})}update(t){return o(this,null,function*(){let e=yield this.set(t);return p(u({},e),{action:"update"})})}};var f=class{static create(t,e){return {success:t.every(r=>r.success),value:e,results:t}}};var W={getter:{get(){return dateVersion.getDateVersion()}},store:new m,targets:[]},G=class{constructor(t){this.logger=new logger.Logger("VersionManager");this.opts=Object.assign({},W,t);}get(){return this.opts.getter.get()}read(){return o(this,null,function*(){let t=this.resolveStores(),e=[];for(let r of t)e.push(yield r.get());return f.create(e)})}set(t){return o(this,null,function*(){this.logger.log("set version: "+t);let e=this.resolveStores(),r=[];for(let s of e)r.push(yield s.set(t));return f.create(r,t)})}update(){return o(this,null,function*(){let t=yield this.get();this.logger.log("new version: "+t);let e=this.resolveStores(),r=[];for(let s of e)r.push(yield s.update(t));return f.create(r,t)})}resolveStores(){var t;return (t=this.opts.targets)!=null&&t.length?this.opts.targets.map(e=>y.create(e)):Array.isArray(this.opts.store)?this.opts.store:[this.opts.store]}};var _t=process.cwd();var P=class{get(){return utils.currentNodeVersion}};var Y=(r=>(r[r.major=0]="major",r[r.minor=1]="minor",r[r.patch=2]="patch",r))(Y||{}),Z={file:"package.json",position:2,key:"version"},N=class{constructor(t){this.opts=Object.assign({},Z,t);}get(){return o(this,null,function*(){if(!(yield fsExtra.pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:t}=yield fsExtra.readJson(this.opts.file);if(!t)throw new Error("get new version, but error: the old version is not found");if(typeof t!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(t)}`);let[e,r,s]=t.split(".");return this.opts.position===0?[Number(e)+1,r,s].join("."):this.opts.position===1?[e,Number(r)+1,s].join("."):[e,r,Number(s)+1].join(".")})}};exports.ConfigStore=l;exports.DEFAULT_JSON_STORE_OPTIONS=D;exports.DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS=Z;exports.DEFAULT_TEXT_STORE_OPTIONS=X;exports.DEFAULT_VERSION_MANAGER_OPTIONS=W;exports.JsonStore=m;exports.NodeVersionGetter=P;exports.Positions=Y;exports.SemanticVersionGetter=N;exports.StoreFactory=y;exports.TextStore=d;exports.VersionManager=G;exports.VersionUpdateResult=f;exports.workspace=_t;

package/dist/lib/index.mjs

@@ -1,5 +1,6 @@
-import {Logger}from'@tikkhun/logger';import {readJson,writeJson,pathExists}from'fs-extra';import k from'fs';import v from'path';import {getDateVersion}from'@tikkhun/date-version';import {currentNodeVersion}from'@tikkhun/utils';/**
+import {Logger}from'@tikkhun/logger';import {pathExists,ensureFile,readFile,writeFile,readJson}from'fs-extra';import {XMLParser,XMLBuilder}from'fast-xml-parser';import R from'js-yaml';import {set,get}from'lodash';import {parse,stringify}from'smol-toml';import {getDateVersion}from'@tikkhun/date-version';import {currentNodeVersion}from'@tikkhun/utils';/**
   @tikkhun/version
-  2025.7.7
+  2026.4.13
 */
-var E=Object.defineProperty,T=Object.defineProperties;var d=Object.getOwnPropertyDescriptors;var m=Object.getOwnPropertySymbols;var N=Object.prototype.hasOwnProperty,_=Object.prototype.propertyIsEnumerable;var c=(e,t,r)=>t in e?E(e,t,{enumerable:true,configurable:true,writable:true,value:r}):e[t]=r,l=(e,t)=>{for(var r in t||(t={}))N.call(t,r)&&c(e,r,t[r]);if(m)for(var r of m(t))_.call(t,r)&&c(e,r,t[r]);return e},g=(e,t)=>T(e,d(t));var n=(e,t,r)=>new Promise((o,s)=>{var w=i=>{try{a(r.next(i));}catch(f){s(f);}},y=i=>{try{a(r.throw(i));}catch(f){s(f);}},a=i=>i.done?o(i.value):Promise.resolve(i.value).then(w,y);a((r=r.apply(e,t)).next());});var V={file:"package.json",key:"version"},p=class{constructor(t){this.opts=Object.assign({},V,t);}update(t){return n(this,null,function*(){try{let r=yield readJson(this.opts.file);return yield writeJson(this.opts.file,g(l({},r),{[this.opts.key]:t}),{spaces:2}),!0}catch(r){return  false}})}};var h=process.cwd();var B={file:""},u=class{constructor(t){this.opts=t,this.filePath=v.join(h,this.opts.file);}update(t){try{return typeof t!="string"&&(t=JSON.stringify(t)),k.writeFileSync(this.filePath,t,"utf8"),!0}catch(r){return  false}}};var A={getter:{get(){return getDateVersion()}},store:new p},O=class{constructor(t){this.logger=new Logger("VersionManager");this.opts=Object.assign({},A,t);}get(){return this.opts.getter.get()}update(){return n(this,null,function*(){let t=yield this.get();this.logger.log("new version: "+t);let r=Array.isArray(this.opts.store)?this.opts.store:[this.opts.store];try{if((yield Promise.all(r.map(s=>s.update(t)))).filter(s=>!s).length)throw new Error("update, but error");return !0}catch(o){return  false}})}};var S=class{get(){return currentNodeVersion}};var R=(o=>(o[o.major=0]="major",o[o.minor=1]="minor",o[o.patch=2]="patch",o))(R||{}),D={file:"package.json",position:2,key:"version"},x=class{constructor(t){this.opts=Object.assign({},D,t);}get(){return n(this,null,function*(){if(!(yield pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:t}=yield readJson(this.opts.file);if(!t)throw new Error("get new version, but error: the old version is not found");if(typeof t!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(t)}`);let[r,o,s]=t.split(".");return this.opts.position===0?[Number(r)+1,o,s].join("."):this.opts.position===1?[r,Number(o)+1,s].join("."):[r,o,Number(s)+1].join(".")})}};export{V as DEFAULT_JSON_STORE_OPTIONS,D as DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS,B as DEFAULT_TEXT_STORE_OPTIONS,A as DEFAULT_VERSION_MANAGER_OPTIONS,p as JsonStore,S as NodeVersionGetter,R as Positions,x as SemanticVersionGetter,u as TextStore,O as VersionManager,h as workspace};
+var b=Object.defineProperty,j=Object.defineProperties;var A=Object.getOwnPropertyDescriptors;var V=Object.getOwnPropertySymbols;var M=Object.prototype.hasOwnProperty,k=Object.prototype.propertyIsEnumerable;var E=(n,t,e)=>t in n?b(n,t,{enumerable:true,configurable:true,writable:true,value:e}):n[t]=e,u=(n,t)=>{for(var e in t||(t={}))M.call(t,e)&&E(n,e,t[e]);if(V)for(var e of V(t))k.call(t,e)&&E(n,e,t[e]);return n},p=(n,t)=>j(n,A(t));var o=(n,t,e)=>new Promise((r,s)=>{var i=a=>{try{g(e.next(a));}catch(S){s(S);}},c=a=>{try{g(e.throw(a));}catch(S){s(S);}},g=a=>a.done?r(a.value):Promise.resolve(a.value).then(i,c);g((e=e.apply(n,t)).next());});var l=class{constructor(t){this.target=t;}get(){return o(this,null,function*(){var t;try{if(!(yield pathExists(this.target.file)))return this.createGetError(`file is not found: ${this.target.file}`);let e=yield this.loadStructuredConfig(),r=this.target.path?get(e,this.target.path):e;return r===void 0?this.createGetError(`path is not found: ${(t=this.target.path)!=null?t:"<root>"}`):typeof r!="string"&&typeof r!="number"?this.createGetError(`value is not string or number: ${JSON.stringify(r)}`):{action:"get",success:!0,file:this.target.file,type:this.target.type,value:r}}catch(e){return this.createGetError(this.getErrorMessage(e))}})}set(t){return o(this,null,function*(){try{let e=yield this.get(),r=e.success?e.value:void 0,s=yield pathExists(this.target.file);if(!s){if(!this.target.createIfNotExists)return this.createSetError(t,`file is not found: ${this.target.file}`,r,"set");yield ensureFile(this.target.file);}let i=s?yield this.loadStructuredConfig():{};if(this.target.path)set(i,this.target.path,t),yield this.saveStructuredConfig(i);else {if(typeof i=="object"&&i!==null&&!Array.isArray(i))return this.createSetError(t,"path is required for structured target",r,"set");yield this.saveStructuredConfig(t);}return {action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:r,newValue:t}}catch(e){return this.createSetError(t,this.getErrorMessage(e),void 0,"set")}})}update(t){return o(this,null,function*(){let e=yield this.set(t);return p(u({},e),{action:"update"})})}createGetError(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t}}createSetError(t,e,r,s="set"){return {action:s,success:false,file:this.target.file,type:this.target.type,oldValue:r,newValue:t,message:e}}getErrorMessage(t){return t instanceof Error?t.message:String(t)}loadStructuredConfig(){return o(this,null,function*(){var e;let t=yield readFile(this.target.file,(e=this.target.encoding)!=null?e:"utf8");switch(this.target.type){case "json":return JSON.parse(t);case "yaml":return R.load(t);case "toml":return parse(t);case "xml":return new XMLParser({ignoreAttributes:true}).parse(t);case "env":return this.parseEnvContent(t);default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}saveStructuredConfig(t){return o(this,null,function*(){var r;let e=(r=this.target.encoding)!=null?r:"utf8";switch(this.target.type){case "json":yield writeFile(this.target.file,JSON.stringify(t,null,2),e);return;case "yaml":yield writeFile(this.target.file,R.dump(t),e);return;case "toml":yield writeFile(this.target.file,stringify(t),e);return;case "xml":yield writeFile(this.target.file,new XMLBuilder({format:true,ignoreAttributes:true}).build(t),e);return;case "env":yield writeFile(this.target.file,this.stringifyEnvContent(t),e);return;default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}parseEnvContent(t){let e={},r=t.split(/\r?\n/);for(let s of r){let i=s.trim();if(!i||i.startsWith("#"))continue;let c=i.indexOf("=");if(c<0)continue;let g=i.slice(0,c).trim(),a=i.slice(c+1).trim();set(e,g.replace(/__/g,"."),a);}return e}stringifyEnvContent(t){let e=[],r=(s,i)=>{if(s!==null&&typeof s=="object"&&!Array.isArray(s)){for(let[g,a]of Object.entries(s))r(a,[...i,g]);return}let c=i.join("__").toUpperCase();e.push(`${c}=${s!=null?s:""}`);};for(let[s,i]of Object.entries(t))r(i,[s]);return e.join(`
+`)}};var D={file:"package.json",key:"version"},m=class extends l{constructor(t){var s;let e=Object.assign({},D,t),r={type:"json",file:e.file,path:(s=e.path)!=null?s:e.key,createIfNotExists:e.createIfNotExists};super(r);}};var X={file:"",mode:"raw",trim:true,replacement:"{{version}}"},d=class{constructor(t){this.target=u(u({type:"text"},X),t);}get(){return o(this,null,function*(){var t;try{if(!(yield pathExists(this.target.file)))return this.createGetError(`file is not found: ${this.target.file}`);let e=yield readFile(this.target.file,(t=this.target.encoding)!=null?t:"utf8"),r=this.resolveValueFromText(e);return r===void 0?this.createGetError("version is not found in text content"):{action:"get",success:!0,file:this.target.file,type:this.target.type,value:r}}catch(e){return this.createGetError(this.getErrorMessage(e))}})}set(t){return o(this,null,function*(){try{let e=yield this.get(),r=e.success?e.value:void 0,s=yield this.createNextText(t);return yield this.writeText(s),{action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:r,newValue:t}}catch(e){return {action:"set",success:false,file:this.target.file,type:this.target.type,newValue:t,message:this.getErrorMessage(e)}}})}update(t){return o(this,null,function*(){let e=yield this.set(t);return p(u({},e),{action:"update"})})}resolveValueFromText(t){var e;if(this.target.mode==="replace"){let s=this.createPattern().exec(t);if(!s)return;let i=(e=s.groups)==null?void 0:e.version;return i!==void 0?i:s[1]!==void 0?s[1]:s[0]}return this.target.trim?t.trim():t}createNextText(t){return o(this,null,function*(){var e,r;if(this.target.mode==="replace"){if(!(yield pathExists(this.target.file)))throw new Error(`file is not found: ${this.target.file}`);let s=yield readFile(this.target.file,(e=this.target.encoding)!=null?e:"utf8");if(!this.createPattern().test(s))throw new Error("pattern is not matched");let c=((r=this.target.replacement)!=null?r:"{{version}}").replaceAll("{{version}}",String(t));return s.replace(this.createPattern(),c)}return String(t)})}writeText(t){return o(this,null,function*(){var e;if(!(yield pathExists(this.target.file))){if(!this.target.createIfNotExists)throw new Error(`file is not found: ${this.target.file}`);yield ensureFile(this.target.file);}yield writeFile(this.target.file,t,(e=this.target.encoding)!=null?e:"utf8");})}createPattern(){if(!this.target.pattern)throw new Error("pattern is required when text mode is replace");return new RegExp(this.target.pattern,this.target.flags)}createGetError(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t}}getErrorMessage(t){return t instanceof Error?t.message:String(t)}};var y=class{static create(t){return t.type==="text"?new d(t):t.type==="custom"?new x(t):new l(t)}},x=class{constructor(t){this.target=t;}get(){return o(this,null,function*(){if(!this.target.get)return {action:"get",success:false,file:this.target.file,type:this.target.type,message:"custom get is not implemented"};try{let t=yield this.target.get(this.target.file);return {action:"get",success:!0,file:this.target.file,type:this.target.type,value:t}}catch(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t instanceof Error?t.message:String(t)}}})}set(t){return o(this,null,function*(){try{let e=yield this.get();return this.target.set?(yield this.target.set(t,this.target.file),{action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:e.success?e.value:void 0,newValue:t}):{action:"set",success:!1,file:this.target.file,type:this.target.type,oldValue:e.success?e.value:void 0,newValue:t,message:"custom set is not implemented"}}catch(e){return {action:"set",success:false,file:this.target.file,type:this.target.type,newValue:t,message:e instanceof Error?e.message:String(e)}}})}update(t){return o(this,null,function*(){let e=yield this.set(t);return p(u({},e),{action:"update"})})}};var f=class{static create(t,e){return {success:t.every(r=>r.success),value:e,results:t}}};var W={getter:{get(){return getDateVersion()}},store:new m,targets:[]},G=class{constructor(t){this.logger=new Logger("VersionManager");this.opts=Object.assign({},W,t);}get(){return this.opts.getter.get()}read(){return o(this,null,function*(){let t=this.resolveStores(),e=[];for(let r of t)e.push(yield r.get());return f.create(e)})}set(t){return o(this,null,function*(){this.logger.log("set version: "+t);let e=this.resolveStores(),r=[];for(let s of e)r.push(yield s.set(t));return f.create(r,t)})}update(){return o(this,null,function*(){let t=yield this.get();this.logger.log("new version: "+t);let e=this.resolveStores(),r=[];for(let s of e)r.push(yield s.update(t));return f.create(r,t)})}resolveStores(){var t;return (t=this.opts.targets)!=null&&t.length?this.opts.targets.map(e=>y.create(e)):Array.isArray(this.opts.store)?this.opts.store:[this.opts.store]}};var _t=process.cwd();var P=class{get(){return currentNodeVersion}};var Y=(r=>(r[r.major=0]="major",r[r.minor=1]="minor",r[r.patch=2]="patch",r))(Y||{}),Z={file:"package.json",position:2,key:"version"},N=class{constructor(t){this.opts=Object.assign({},Z,t);}get(){return o(this,null,function*(){if(!(yield pathExists(this.opts.file)))throw new Error("get new version,but error: the file is not found");let{[this.opts.key]:t}=yield readJson(this.opts.file);if(!t)throw new Error("get new version, but error: the old version is not found");if(typeof t!="string")throw new Error(`get new version, but error: the old version is not string,old version: ${JSON.stringify(t)}`);let[e,r,s]=t.split(".");return this.opts.position===0?[Number(e)+1,r,s].join("."):this.opts.position===1?[e,Number(r)+1,s].join("."):[e,r,Number(s)+1].join(".")})}};export{l as ConfigStore,D as DEFAULT_JSON_STORE_OPTIONS,Z as DEFAULT_SEMANTIC_VERSION_GETTER_OPTIONS,X as DEFAULT_TEXT_STORE_OPTIONS,W as DEFAULT_VERSION_MANAGER_OPTIONS,m as JsonStore,P as NodeVersionGetter,Y as Positions,N as SemanticVersionGetter,y as StoreFactory,d as TextStore,G as VersionManager,f as VersionUpdateResult,_t as workspace};

package/dist/lib/store/ConfigStore.d.mts

@@ -0,0 +1,69 @@
+import { Store, StructuredVersionTarget, StoreGetResult, VersionValue, StoreSetResult } from './Store.mjs';
+
+/**
+ * @description 结构化配置 store.
+ */
+declare class ConfigStore implements Store {
+    /**
+     * @description 当前 store 绑定的目标.
+     */
+    target: StructuredVersionTarget;
+    /**
+     * @description 初始化结构化配置 store.
+     * @param target 目标配置.
+     */
+    constructor(target: StructuredVersionTarget);
+    /**
+     * @description 读取结构化文件里的版本值.
+     */
+    get(): Promise<StoreGetResult>;
+    /**
+     * @description 写入结构化文件里的版本值.
+     * @param value 版本值.
+     */
+    set(value: VersionValue): Promise<StoreSetResult>;
+    /**
+     * @description 更新结构化文件里的版本值.
+     * @param value 版本值.
+     */
+    update(value: VersionValue): Promise<StoreSetResult>;
+    /**
+     * @description 创建读取失败结果.
+     * @param message 错误消息.
+     */
+    protected createGetError(message: string): StoreGetResult;
+    /**
+     * @description 创建写入失败结果.
+     * @param value 目标版本值.
+     * @param message 错误消息.
+     * @param oldValue 旧版本值.
+     * @param action 操作名称.
+     */
+    protected createSetError(value: VersionValue, message: string, oldValue?: VersionValue, action?: 'set' | 'update'): StoreSetResult;
+    /**
+     * @description 提取异常消息.
+     * @param error 异常对象.
+     */
+    protected getErrorMessage(error: unknown): string;
+    /**
+     * @description 读取结构化配置.
+     */
+    protected loadStructuredConfig(): Promise<any>;
+    /**
+     * @description 保存结构化配置.
+     * @param config 配置对象.
+     */
+    protected saveStructuredConfig(config: any): Promise<void>;
+    /**
+     * @description 解析 env 文本.
+     * @param fileContent 文件内容.
+     */
+    protected parseEnvContent(fileContent: string): Record<string, unknown>;
+    /**
+     * @description 序列化 env 对象.
+     * @param config 配置对象.
+     */
+    protected stringifyEnvContent(config: Record<string, unknown>): string;
+}
+
+export { ConfigStore };

package/dist/lib/store/ConfigStore.d.ts

@@ -0,0 +1,69 @@
+import { Store, StructuredVersionTarget, StoreGetResult, VersionValue, StoreSetResult } from './Store.js';
+
+/**
+ * @description 结构化配置 store.
+ */
+declare class ConfigStore implements Store {
+    /**
+     * @description 当前 store 绑定的目标.
+     */
+    target: StructuredVersionTarget;
+    /**
+     * @description 初始化结构化配置 store.
+     * @param target 目标配置.
+     */
+    constructor(target: StructuredVersionTarget);
+    /**
+     * @description 读取结构化文件里的版本值.
+     */
+    get(): Promise<StoreGetResult>;
+    /**
+     * @description 写入结构化文件里的版本值.
+     * @param value 版本值.
+     */
+    set(value: VersionValue): Promise<StoreSetResult>;
+    /**
+     * @description 更新结构化文件里的版本值.
+     * @param value 版本值.
+     */
+    update(value: VersionValue): Promise<StoreSetResult>;
+    /**
+     * @description 创建读取失败结果.
+     * @param message 错误消息.
+     */
+    protected createGetError(message: string): StoreGetResult;
+    /**
+     * @description 创建写入失败结果.
+     * @param value 目标版本值.
+     * @param message 错误消息.
+     * @param oldValue 旧版本值.
+     * @param action 操作名称.
+     */
+    protected createSetError(value: VersionValue, message: string, oldValue?: VersionValue, action?: 'set' | 'update'): StoreSetResult;
+    /**
+     * @description 提取异常消息.
+     * @param error 异常对象.
+     */
+    protected getErrorMessage(error: unknown): string;
+    /**
+     * @description 读取结构化配置.
+     */
+    protected loadStructuredConfig(): Promise<any>;
+    /**
+     * @description 保存结构化配置.
+     * @param config 配置对象.
+     */
+    protected saveStructuredConfig(config: any): Promise<void>;
+    /**
+     * @description 解析 env 文本.
+     * @param fileContent 文件内容.
+     */
+    protected parseEnvContent(fileContent: string): Record<string, unknown>;
+    /**
+     * @description 序列化 env 对象.
+     * @param config 配置对象.
+     */
+    protected stringifyEnvContent(config: Record<string, unknown>): string;
+}
+
+export { ConfigStore };

package/dist/lib/store/ConfigStore.js

@@ -0,0 +1,6 @@
+'use strict';var fsExtra=require('fs-extra'),fastXmlParser=require('fast-xml-parser'),m=require('js-yaml'),lodash=require('lodash'),smolToml=require('smol-toml');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var m__default=/*#__PURE__*/_interopDefault(m);/**
+  @tikkhun/version
+  2026.4.13
+*/
+var E=Object.defineProperty,V=Object.defineProperties;var C=Object.getOwnPropertyDescriptors;var l=Object.getOwnPropertySymbols;var R=Object.prototype.hasOwnProperty,b=Object.prototype.propertyIsEnumerable;var h=(n,t,e)=>t in n?E(n,t,{enumerable:true,configurable:true,writable:true,value:e}):n[t]=e,p=(n,t)=>{for(var e in t||(t={}))R.call(t,e)&&h(n,e,t[e]);if(l)for(var e of l(t))b.call(t,e)&&h(n,e,t[e]);return n},d=(n,t)=>V(n,C(t));var c=(n,t,e)=>new Promise((r,s)=>{var i=a=>{try{u(e.next(a));}catch(f){s(f);}},o=a=>{try{u(e.throw(a));}catch(f){s(f);}},u=a=>a.done?r(a.value):Promise.resolve(a.value).then(i,o);u((e=e.apply(n,t)).next());});var S=class{constructor(t){this.target=t;}get(){return c(this,null,function*(){var t;try{if(!(yield fsExtra.pathExists(this.target.file)))return this.createGetError(`file is not found: ${this.target.file}`);let e=yield this.loadStructuredConfig(),r=this.target.path?lodash.get(e,this.target.path):e;return r===void 0?this.createGetError(`path is not found: ${(t=this.target.path)!=null?t:"<root>"}`):typeof r!="string"&&typeof r!="number"?this.createGetError(`value is not string or number: ${JSON.stringify(r)}`):{action:"get",success:!0,file:this.target.file,type:this.target.type,value:r}}catch(e){return this.createGetError(this.getErrorMessage(e))}})}set(t){return c(this,null,function*(){try{let e=yield this.get(),r=e.success?e.value:void 0,s=yield fsExtra.pathExists(this.target.file);if(!s){if(!this.target.createIfNotExists)return this.createSetError(t,`file is not found: ${this.target.file}`,r,"set");yield fsExtra.ensureFile(this.target.file);}let i=s?yield this.loadStructuredConfig():{};if(this.target.path)lodash.set(i,this.target.path,t),yield this.saveStructuredConfig(i);else {if(typeof i=="object"&&i!==null&&!Array.isArray(i))return this.createSetError(t,"path is required for structured target",r,"set");yield this.saveStructuredConfig(t);}return {action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:r,newValue:t}}catch(e){return this.createSetError(t,this.getErrorMessage(e),void 0,"set")}})}update(t){return c(this,null,function*(){let e=yield this.set(t);return d(p({},e),{action:"update"})})}createGetError(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t}}createSetError(t,e,r,s="set"){return {action:s,success:false,file:this.target.file,type:this.target.type,oldValue:r,newValue:t,message:e}}getErrorMessage(t){return t instanceof Error?t.message:String(t)}loadStructuredConfig(){return c(this,null,function*(){var e;let t=yield fsExtra.readFile(this.target.file,(e=this.target.encoding)!=null?e:"utf8");switch(this.target.type){case "json":return JSON.parse(t);case "yaml":return m__default.default.load(t);case "toml":return smolToml.parse(t);case "xml":return new fastXmlParser.XMLParser({ignoreAttributes:true}).parse(t);case "env":return this.parseEnvContent(t);default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}saveStructuredConfig(t){return c(this,null,function*(){var r;let e=(r=this.target.encoding)!=null?r:"utf8";switch(this.target.type){case "json":yield fsExtra.writeFile(this.target.file,JSON.stringify(t,null,2),e);return;case "yaml":yield fsExtra.writeFile(this.target.file,m__default.default.dump(t),e);return;case "toml":yield fsExtra.writeFile(this.target.file,smolToml.stringify(t),e);return;case "xml":yield fsExtra.writeFile(this.target.file,new fastXmlParser.XMLBuilder({format:true,ignoreAttributes:true}).build(t),e);return;case "env":yield fsExtra.writeFile(this.target.file,this.stringifyEnvContent(t),e);return;default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}parseEnvContent(t){let e={},r=t.split(/\r?\n/);for(let s of r){let i=s.trim();if(!i||i.startsWith("#"))continue;let o=i.indexOf("=");if(o<0)continue;let u=i.slice(0,o).trim(),a=i.slice(o+1).trim();lodash.set(e,u.replace(/__/g,"."),a);}return e}stringifyEnvContent(t){let e=[],r=(s,i)=>{if(s!==null&&typeof s=="object"&&!Array.isArray(s)){for(let[u,a]of Object.entries(s))r(a,[...i,u]);return}let o=i.join("__").toUpperCase();e.push(`${o}=${s!=null?s:""}`);};for(let[s,i]of Object.entries(t))r(i,[s]);return e.join(`
+`)}};exports.ConfigStore=S;

package/dist/lib/store/ConfigStore.mjs

@@ -0,0 +1,6 @@
+import {pathExists,ensureFile,readFile,writeFile}from'fs-extra';import {XMLParser,XMLBuilder}from'fast-xml-parser';import m from'js-yaml';import {set,get}from'lodash';import {parse,stringify}from'smol-toml';/**
+  @tikkhun/version
+  2026.4.13
+*/
+var E=Object.defineProperty,V=Object.defineProperties;var C=Object.getOwnPropertyDescriptors;var l=Object.getOwnPropertySymbols;var R=Object.prototype.hasOwnProperty,b=Object.prototype.propertyIsEnumerable;var h=(n,t,e)=>t in n?E(n,t,{enumerable:true,configurable:true,writable:true,value:e}):n[t]=e,p=(n,t)=>{for(var e in t||(t={}))R.call(t,e)&&h(n,e,t[e]);if(l)for(var e of l(t))b.call(t,e)&&h(n,e,t[e]);return n},d=(n,t)=>V(n,C(t));var c=(n,t,e)=>new Promise((r,s)=>{var i=a=>{try{u(e.next(a));}catch(f){s(f);}},o=a=>{try{u(e.throw(a));}catch(f){s(f);}},u=a=>a.done?r(a.value):Promise.resolve(a.value).then(i,o);u((e=e.apply(n,t)).next());});var S=class{constructor(t){this.target=t;}get(){return c(this,null,function*(){var t;try{if(!(yield pathExists(this.target.file)))return this.createGetError(`file is not found: ${this.target.file}`);let e=yield this.loadStructuredConfig(),r=this.target.path?get(e,this.target.path):e;return r===void 0?this.createGetError(`path is not found: ${(t=this.target.path)!=null?t:"<root>"}`):typeof r!="string"&&typeof r!="number"?this.createGetError(`value is not string or number: ${JSON.stringify(r)}`):{action:"get",success:!0,file:this.target.file,type:this.target.type,value:r}}catch(e){return this.createGetError(this.getErrorMessage(e))}})}set(t){return c(this,null,function*(){try{let e=yield this.get(),r=e.success?e.value:void 0,s=yield pathExists(this.target.file);if(!s){if(!this.target.createIfNotExists)return this.createSetError(t,`file is not found: ${this.target.file}`,r,"set");yield ensureFile(this.target.file);}let i=s?yield this.loadStructuredConfig():{};if(this.target.path)set(i,this.target.path,t),yield this.saveStructuredConfig(i);else {if(typeof i=="object"&&i!==null&&!Array.isArray(i))return this.createSetError(t,"path is required for structured target",r,"set");yield this.saveStructuredConfig(t);}return {action:"set",success:!0,file:this.target.file,type:this.target.type,oldValue:r,newValue:t}}catch(e){return this.createSetError(t,this.getErrorMessage(e),void 0,"set")}})}update(t){return c(this,null,function*(){let e=yield this.set(t);return d(p({},e),{action:"update"})})}createGetError(t){return {action:"get",success:false,file:this.target.file,type:this.target.type,message:t}}createSetError(t,e,r,s="set"){return {action:s,success:false,file:this.target.file,type:this.target.type,oldValue:r,newValue:t,message:e}}getErrorMessage(t){return t instanceof Error?t.message:String(t)}loadStructuredConfig(){return c(this,null,function*(){var e;let t=yield readFile(this.target.file,(e=this.target.encoding)!=null?e:"utf8");switch(this.target.type){case "json":return JSON.parse(t);case "yaml":return m.load(t);case "toml":return parse(t);case "xml":return new XMLParser({ignoreAttributes:true}).parse(t);case "env":return this.parseEnvContent(t);default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}saveStructuredConfig(t){return c(this,null,function*(){var r;let e=(r=this.target.encoding)!=null?r:"utf8";switch(this.target.type){case "json":yield writeFile(this.target.file,JSON.stringify(t,null,2),e);return;case "yaml":yield writeFile(this.target.file,m.dump(t),e);return;case "toml":yield writeFile(this.target.file,stringify(t),e);return;case "xml":yield writeFile(this.target.file,new XMLBuilder({format:true,ignoreAttributes:true}).build(t),e);return;case "env":yield writeFile(this.target.file,this.stringifyEnvContent(t),e);return;default:throw new Error(`unsupported structured target type: ${this.target.type}`)}})}parseEnvContent(t){let e={},r=t.split(/\r?\n/);for(let s of r){let i=s.trim();if(!i||i.startsWith("#"))continue;let o=i.indexOf("=");if(o<0)continue;let u=i.slice(0,o).trim(),a=i.slice(o+1).trim();set(e,u.replace(/__/g,"."),a);}return e}stringifyEnvContent(t){let e=[],r=(s,i)=>{if(s!==null&&typeof s=="object"&&!Array.isArray(s)){for(let[u,a]of Object.entries(s))r(a,[...i,u]);return}let o=i.join("__").toUpperCase();e.push(`${o}=${s!=null?s:""}`);};for(let[s,i]of Object.entries(t))r(i,[s]);return e.join(`
+`)}};export{S as ConfigStore};

package/dist/lib/store/JsonStore.d.mts

@@ -1,17 +1,40 @@
-import { Store } from './Store.mjs';
+import { ConfigStore } from './ConfigStore.mjs';
+import './Store.mjs';
 
+/**
+ * @description JSON store 配置.
+ */
 interface JsonStoreOptions {
+    /**
+     * @description 目标文件路径.
+     */
     file: string;
-    key: string;
+    /**
+     * @description 兼容旧版本的 key 配置.
+     */
+    key?: string;
+    /**
+     * @description 新版推荐的对象路径配置.
+     */
+    path?: string;
+    /**
+     * @description 文件不存在时是否允许创建.
+     */
+    createIfNotExists?: boolean;
 }
-declare const DEFAULT_JSON_STORE_OPTIONS: {
-    file: string;
-    key: string;
-};
-declare class JsonStore implements Store {
-    opts: JsonStoreOptions;
+/**
+ * @description JSON store 默认配置.
+ */
+declare const DEFAULT_JSON_STORE_OPTIONS: JsonStoreOptions;
+/**
+ * @description JSON 版本 store.
+ */
+declare class JsonStore extends ConfigStore {
+    /**
+     * @description 初始化 JSON store.
+     * @param options store 配置.
+     */
     constructor(options?: Partial<JsonStoreOptions>);
-    update(value: any): Promise<boolean>;
 }
 
 export { DEFAULT_JSON_STORE_OPTIONS, JsonStore, type JsonStoreOptions };

package/dist/lib/store/JsonStore.d.ts

@@ -1,17 +1,40 @@
-import { Store } from './Store.js';
+import { ConfigStore } from './ConfigStore.js';
+import './Store.js';
 
+/**
+ * @description JSON store 配置.
+ */
 interface JsonStoreOptions {
+    /**
+     * @description 目标文件路径.
+     */
     file: string;
-    key: string;
+    /**
+     * @description 兼容旧版本的 key 配置.
+     */
+    key?: string;
+    /**
+     * @description 新版推荐的对象路径配置.
+     */
+    path?: string;
+    /**
+     * @description 文件不存在时是否允许创建.
+     */
+    createIfNotExists?: boolean;
 }
-declare const DEFAULT_JSON_STORE_OPTIONS: {
-    file: string;
-    key: string;
-};
-declare class JsonStore implements Store {
-    opts: JsonStoreOptions;
+/**
+ * @description JSON store 默认配置.
+ */
+declare const DEFAULT_JSON_STORE_OPTIONS: JsonStoreOptions;
+/**
+ * @description JSON 版本 store.
+ */
+declare class JsonStore extends ConfigStore {
+    /**
+     * @description 初始化 JSON store.
+     * @param options store 配置.
+     */
     constructor(options?: Partial<JsonStoreOptions>);
-    update(value: any): Promise<boolean>;
 }
 
 export { DEFAULT_JSON_STORE_OPTIONS, JsonStore, type JsonStoreOptions };