@isdk/util 0.3.8 → 0.3.10

package/dist/index.mjs

@@ -1 +1 @@
-import{existsSync as t,mkdirSync as s,readFileSync as n,writeFileSync as r}from"fs";import i from"path";import{Config as e}from"load-config-file";import o from"path";function c(t,s=1){let n="";for(;s--;){const s=o.extname(t);if(!s)break;n=s+n,t=o.basename(t,s)}return n}import{parse as h,stringify as u}from"yaml";var f=[];function a(t){Array.isArray(t)||(t=[t]);for(const s of t){-1===f.indexOf(s)&&f.push(s)}}function l(t,s){if(s)if(s.customTags){if(Array.isArray(s.customTags))s.customTags=f.concat(s.customTags);else if("function"==typeof s.customTags){const t=s.customTags;s.customTags=s=>t(f.concat(s))}}else s.customTags=f;else s={customTags:f};return h(t,s)}function m(t,s){if(s)if(s.customTags){if(Array.isArray(s.customTags))s.customTags=f.concat(s.customTags);else if("function"==typeof s.customTags){const t=s.customTags;s.customTags=s=>t(f.concat(s))}}else s.customTags=f;else s={customTags:f};return u(t,s)}function p(t){const s=/^\s*(#[^\r\n]*)?[\r\n]+/;let n;for(;null!==(n=s.exec(t))&&((t=t.substring(n[0].length)).startsWith("\n")||t.startsWith("\r")||t.trimStart().startsWith("#")););return t}function y(t,s="---"){const n=s.length,r=p(t);if(r.startsWith(s)&&("\n"===r[s.length]||"\r"===r[s.length])){let t=r.indexOf("\n"+s,n);if(-1!==t){const i=r.slice(n,t);for(t+=s.length+1;"\n"===r[t]||"\r"===r[t];)t++;const e=r.slice(t);return{data:l(i)||{},content:e}}}return{data:{},content:t}}var d=class{static register(t,s,n){e.register(t,s),"string"==typeof t&&(t=[t]);for(const s of t)this.stringifys[s]=n}static loadSync(s,r){return function(s,{extLevel:r=1,externalFile:o}={}){s=g(s,r);let c=e.loadSync(s);if(!c&&o){if(!i.isAbsolute(o)){const t=i.dirname(s);o=i.join(t,o)}if(t(o)){const t=y(n(o,"utf8")).data;Object.keys(t).length&&(c=t)}}return c}(s,r)}static saveSync(n,e,o){return function(n,e,{extLevel:o=1}={}){const h=function(t,s=1){"."===t[0]&&s++;let n=c(t,s);(!n||n.split(".").length<=1)&&(t+=".yaml",n=".yaml");const r=new String(t);return r.extname=n,r}(n,o),u=h.extname;n=h.toString();const f=d.stringifys[u];if(!f)throw new Error(`${n} unsupported mime type: ${u}`);e=f(e);const a=i.dirname(n);t(a)||s(a,{recursive:!0});return r(n,e,{encoding:"utf8"}),n}(n,e,o)}static existsSync(t,s){return t=g(t,s?.extLevel),e.existsSync(t,s)}};function g(t,s=1){"."===t[0]&&s++;const n=c(t,s);return n&&n.split(".").length>1&&(t=t.slice(0,-n.length)),t}d.stringifys={},d.register([".yml",".yaml"],l,m),d.register([".json"],function(t){return JSON.parse(t)},t=>JSON.stringify(t,null,2));import{globMatch as v}from"@isdk/glob";import w from"path";function b(t,s,n){return n&&(t=w.relative(n,t)),v(t,s)}function k(t,s){return"string"==typeof s&&(s=[s]),-1!==s.indexOf(t)}var x=["**/*.((j|t)s?(x)|m(j|t)s)?(x)","**/*.(md|markdown|txt|?(x)htm?(l)|yaml|yml|xml|json|bat|sh|bash|zsh|ini|css|scss|less|sass|py|rb|php|go|java|c|cpp|h|hpp|hxx|rust|zig)"];function F(t,s=[]){if(t)if(Array.isArray(t))t=[...t];else{const n=t.include||[],r=t.exclude||[];0===n.length&&n.push(...s),t=[...n];for(const s of r)t.push(`!${s}`)}else t=[...s];return 0===t.length&&t.push(...s),t}import{readdir as j}from"fs/promises";import{readdirSync as A}from"fs";import E from"path";async function S(t,s){const n=await j(t,{withFileTypes:!0});for(const r of n){const n=E.join(t,r.name);try{if(r.isDirectory()){await s(n,r)||await S(n,s)}else{if(!0===await s(n,r))break}}catch(t){console.error(`Error processing file: ${n}`),console.error(t)}}}function $(t,s){const n=A(t,{withFileTypes:!0});for(const r of n){const n=E.join(t,r.name);try{if(r.isDirectory()){s(n,r)||S(n,s)}else{if(!0===s(n,r))break}}catch(t){console.error(`Error processing file: ${n}`),console.error(t)}}}function P(t){if(!t)return"";return t.replace(/[-_ ]+/g," ").split(" ").filter(Boolean).map(t=>{let s=t.charAt(0).toUpperCase();t=t.slice(1);let n=0;for(;/[A-Z]/.test(t[n]);)n++;return s+=n?t.slice(0,n).toLowerCase()+t.slice(n):t,s}).join("")}function O(t){return(t=P(t)).charAt(0).toLowerCase()+t.slice(1)}function T(t){if(!t)return"";return t.replace(/[-_ ]+/g," ").replace(/([a-z])([A-Z])/g,"$1 $2").split(" ").filter(Boolean).map(t=>t.charAt(0).toUpperCase()+t.slice(1).toLowerCase()).join(" ")}import z from"path";import{ErrorCode as R,throwError as M}from"@isdk/common-error";var N=/[<>:"/\\|?*\u0000-\u001F]/,C=/^(con|prn|aux|nul|com\d|lpt\d)$/i,D=/^\.+(\\|\/)|^\.+$/,_=/\.+$/,q=/[\u0000-\u001F\u0080-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/;function B(){return new RegExp(N.source,"g")}function I(){return new RegExp(q.source,"g")}function J(t){return t&&!(N.test(t)||I().test(t)||D.test(t)||_.test(t))}function L(t){const s=t.split(z.sep);return("/"===t[0]||s[0]&&z.dirname(s[0])===s[0])&&s.shift(),s.every(J)}function U(t,s={}){const n=s.replacement||"!";if((N.test(n)||q.test(n))&&M("Replacement string cannot contain reserved filename characters","sanitizeFilename",R.InvalidArgument),n.length>0){const s=/([<>:"/\\|?*\u0000-\u001F]){2,}/;t=t.replace(s,"$1")}if(t=(t=(t=(t=(t=t.normalize("NFD")).replace(D,n)).replace(B(),n)).replace(I(),n)).replace(_,""),n.length>0){"."===t[0]||"."!==t[0]||(t=n+t),"."===t[t.length-1]&&(t+=n)}t=C.test(t)?t+n:t;const r="number"==typeof s.maxLength?s.maxLength:100;if(t.length>r){const s=t.lastIndexOf(".");if(-1===s)t=t.slice(0,r);else{const n=t.slice(0,s),i=t.slice(s);t=n.slice(0,Math.max(1,r-i.length))+i}}return t}function Z(t,s={}){const n=t.split(z.sep);let r;("/"===t[0]||n[0]&&z.dirname(n[0])===n[0])&&(r=n.shift());const i=n.map(t=>U(t,s));return void 0!==r&&i.unshift(r),i.join(z.sep)}function G(t){return t.split(".").length-1}function W(t,s){const n=new Set(s),r=new Set;for(const s of t)if(n.has(s)&&(r.add(s),r.size===n.size))return!0;return r.size===n.size}function H(t=0){return s=Math.min(Math.max(16,t),1073741824),s>>>=0,s-=1,s|=s>>1,s|=s>>2,s|=s>>4,s|=s>>8,1+(s|=s>>16);var s}var K=class extends Array{constructor(t,s){Array.isArray(t)?(super(...t),this._length=t.length,t=void 0):(super(),this._length=0),this._capacity=H(t),this._front=0,this._disableAutoResize=s}push(t){let s=this._length;this.checkCapacity(s+1);const n=this._front+s&this._capacity-1;return this[n]=t,++s<=this._capacity&&(this._length=s),n}unshift(t){let s=this._length;this.checkCapacity(++s);const n=this._capacity,r=(this._front-1&n-1^n)-n;return this[r]=t,this._front=r,s<=this._capacity&&(this._length=s),r}pop(t){let s=this._length;if(0===s)return;let n=this._front+s-1&this._capacity-1,r=this[n];for(;--s>0&&t&&null==r;)n--,r=this[n];return this[n]=void 0,this._length=s,r}shift(t){let s=this._length;if(0===s)return;let n=this._front,r=this[n];for(;--s>0&&t&&null==r;)n=n+1&this._capacity-1,r=this[n];return this[n]=void 0,this._front=n+1&this._capacity-1,this._length=s,r}get size(){return this._length}get(t){let s;if(t===(0|t)){const n=this._length;t<0&&(t+=n),t>=0&&t<n&&(s=this[this._front+t&this._capacity-1])}return s}peekBack(){const t=this._length;if(0===t)return;return this[this._front+t-1&this._capacity-1]}peekFront(){if(0!==this._length)return this[this._front]}clear(){const t=this._length,s=this._front,n=this._capacity;for(let r=0;r<t;++r)this[s+r&n-1]=void 0;this._length=0,this._front=0}isEmpty(){return 0===this._length}removeAt(t){const s=this._length;if(t<0||t>=s)return;const n=this._front,r=this._capacity-1,i=n+t&r,e=this[i];if(t<s/2)this.copyWithin(n+1&r,n,n+t&r),this[n]=void 0,this._front=n+1&r;else{this.copyWithin(i,i+1&r,n+s&r);this[n+s-1&r]=void 0}return this._length=s-1,e}checkCapacity(t){this._capacity<t&&!this._disableAutoResize&&this.resizeTo(H(1.5*this._capacity+16))}resizeTo(t){const s=this._capacity;this._capacity=t;const n=this._front,r=this._length;if(n+r>s){!function(t,s,n,r,i){for(let e=0;e<i;++e)n[e+r]=t[e+s],t[e+s]=void 0}(this,0,this,s,n+r&s-1)}}},Q=class t{constructor(t=0){this.bitField=t}static has(t,s){return!!(t&1<<s)}static add(t,s){return t|1<<s}static delete(t,s){return t&~(1<<s)}add(t){return this.bitField|=1<<t,this}delete(t){return this.bitField&=~(1<<t),this}has(s){return t.has(this.bitField,s)}clear(){return this.bitField=0,this}valueOf(){return this.bitField}toString(){return this.bitField.toString()}toJSON(){return this.bitField}};async function V(t){return new Promise(s=>setTimeout(s,t))}async function X(){return new Promise(t=>{setImmediate(t)})}import{isAsync as Y}from"util-ex";import{EventEmitter as tt}from"events-ex";import{AbortError as st}from"@isdk/common-error";var nt=32;function rt(t){return"function"==typeof t}function it(){return"1"}var et=class{constructor(t={}){const{initFn:s=it,pauseFn:n,resumeFn:r,capacity:i=nt}=t;if(rt(n)!==rt(r))throw new Error("pauseFn and resumeFn must be both set for pausing");this.waiting=new K(i),this.emitter=new tt,this.useDefaultTokens=s===it,this.pauseFn=n,this.resumeFn=r,this.initTokenFn=s,this.paused=!1,this._activeCount=0,this.initFree(t),this.init(t)}initFree(t){this.free=this.initTokenFn()}onReleased(t){const s=t?.token,n=this.waiting.shift(!0);n?this._dispatchTask(n,t):(this.resumeFn&&this.paused&&(this.paused=!1,this.resumeFn()),this.unlock(s))}init(t){this.emitter.on("release",t=>{this.onReleased(t)})}_newReleaser(t){let s=!1;const n=()=>{s||(s=!0,this.release(t))};return t&&Object.assign(n,t),n}_dispatchTask(t,s){const{resolve:n}=t;n(this._newReleaser(s))}lock(t){const s=this.free;if(s)return this.free=void 0,s}unlock(t){this.free=this.useDefaultTokens?"1":t??this.initTokenFn()}tryAcquire(t){return this.lock(t)}async acquire(t){this._activeCount++;const s=t?.signal,n=t=>{this.pauseFn&&!this.paused&&(this.paused=!0,this.pauseFn());const n=this.waiting.push(t),r=t.reject;return s&&s.addEventListener("abort",()=>{this.waiting[n]=void 0;const t=s.reason instanceof Error?s.reason:new st(s.reason||"aborted");s.alreadyRejected=!0,r(t)}),n},r=this.tryAcquire(t),i=r&&Y(r),e=s=>new Promise((r,i)=>{const e={...t,resolve:r,reject:i,token:s};void 0===s?n(e):this._dispatchTask(e,{...t,token:s})});return i?r.then(t=>e(t)):e(r)}release(t){this._activeCount--,this.emitter.emit("release",t)}drain(){const t=[this.acquire()];return Promise.all(t)}abort(t){let s;for(;s=this.waiting.shift(!0);)s.reject(new st(t))}get activeCount(){return this._activeCount}get pendingCount(){return this.waiting.size}},ot=class extends et{constructor(t,s){if("number"==typeof t)(s=s||{}).maxConcurrency=t;else if("number"!=typeof(s=t).maxConcurrency)throw new Error("maxConcurrency must be set");super(s),this.maxConcurrency=s.maxConcurrency,s.isReadyFn&&(this.isReady=s.isReadyFn)}initFree(t){const s=t.maxConcurrency=Math.max(1,t.maxConcurrency);this.free=new K(s);for(let t=0;t<s;t++)this.free.push(this.initTokenFn())}tryAcquire(t){let s=this.isReady;if(s&&Y(s)){return s instanceof Promise||(s=s()),s.then(s=>{if(s)return this.lock(t)})}if(!s||s())return this.lock(t)}unlock(t){this.free.push(this.useDefaultTokens?"1":t??this.initTokenFn())}lock(t){return this.free.pop()}drain(){const t=new Array(this.maxConcurrency);for(let s=0;s<this.maxConcurrency;s++)t[s]=this.acquire();return Promise.all(t)}};function ct(t,{timeUnit:s=1e3,uniformDistribution:n=!1}={}){const r=new ot(n?1:t),i=n?s/t:s;return async function(){await r.acquire(),setTimeout(()=>r.release(),i)}}import{AbortError as ht}from"@isdk/common-error";var ut=class{constructor(){this._isSignaled=!1,this.waitQueue=[]}get signaled(){return this._isSignaled}signal(t){if(this._isSignaled)return;this._isSignaled=!0,this._signalValue=t;const s=this.waitQueue.slice();for(this.waitQueue.length=0;s.length>0;){const t=s.shift();t?.resolve(this._signalValue)}}reset(){this._isSignaled=!1,this._signalValue=void 0,this.waitQueue.length=0}abort(t){if(this.waitQueue.length){const s=this.waitQueue.slice();this.waitQueue.length=0;const n=new ht(t);for(;s.length>0;){const{reject:t}=s.shift();t(n)}}}async wait(){return new Promise((t,s)=>{this._isSignaled?t(this._signalValue):this.waitQueue.push({resolve:t,reject:s})})}};import ft from"net";async function at(t,s=10){return new Promise((n,r)=>{void 0===t?t=0:("string"==typeof t&&(t=parseInt(t)),t>=0||(t=0));const i=ft.createServer();i.on("error",n=>{"EADDRINUSE"===n.code&&(t++,--s>0)?i.listen(t):r(n)}),i.on("listening",async()=>{const t=i.address().port;i.close(s=>{s?r(s):n(t)})}),i.listen(t)})}import{isEmpty as lt,isNil as mt,isObject as pt,isPlainObject as yt}from"lodash-es";function dt(t,s,n=new WeakMap){if(!pt(t)||mt(t))return t;if(n.has(t))return n.get(t);let r;if(Array.isArray(t)){r=[],n.set(t,r);const i=t.map(t=>dt(t,s,n)).filter((t,n)=>!s(t,n.toString()));return Object.assign(r,i),r.length>0?r:void 0}if(yt(t)){r={},n.set(t,r);const i=Reflect.ownKeys(t);for(const e of i){const i=dt(t[e],s,n);s(i,e)||(r[e]=i)}return lt(r)?void 0:r}return t}import{isArray as gt,isEmpty as vt,isNil as wt,isPlainObject as bt}from"lodash-es";var kt=(t,s)=>dt(t,t=>function(t){return!!wt(t)||"string"==typeof t&&0===t.trim().length||!(!gt(t)&&!bt(t))&&vt(t)}(t)||s&&"function"==typeof t),xt={javascript:"js",jsx:"js",typescript:"ts",tsx:"ts",markdown:"md",python:"py",ruby:"rb",bash:"sh",zsh:"sh",shell:"sh",yaml:"yml",golang:"go",rust:"rs","c#":"cs",csharp:"cs","c++":"cpp"};function Ft(t,s){if(!t)return t;const n=t.toLowerCase();return s&&n in s?s[n]:xt[n]||n}function jt(t,s={}){const{lang:n,langMap:r}=s,i=Ft(n,r),e=/^[ \t]*(?<fence>`{3,}|~{3,})(?<lang>\S*)[ \t]*(?<meta>\S*?)\n(?<code>[\s\S]+?\n)?[ \t]*\k<fence>$/gm,o=[];let c;for(e.lastIndex=0;null!==(c=e.exec(t));){const t=c.groups?.lang?.toLowerCase();if(!i||i===Ft(t,r)){const t=c.groups.code||"",s=new String(t);c.groups.lang&&(s.lang=c.groups.lang.toLowerCase()),c.groups.meta&&(s.meta=c.groups.meta),o.push(s)}}return o}function At(t){if(!t)return[];const s=[],n=/([>+~])?\s*([^\s>+~]+)/g;let r;for(;null!==(r=n.exec(t));){const t=r[1]||" ",n=r[2];s.push({combinator:t,lang:n})}return s}function Et(t,s){const n="string"==typeof s?{lang:s}:s??{},{index:r=-1,all:i}=n,e=At(n.lang);let o=[];if(0===e.length)o=jt(t,n);else{let s=[t];for(let t=0;t<e.length;t++){const{combinator:r,lang:i}=e[t],c=t===e.length-1,h=[],u=0===t&&" "===r?">":r;for(const t of s){let s=[];switch(u){case">":s=jt(t,{...n,lang:i,all:!0});break;case" ":console.warn('Descendant selector " " is not implemented yet.');break;case"+":console.warn('Adjacent sibling selector "+" is not implemented yet.');break;case"~":console.warn('General sibling selector "~" is not implemented yet.')}h.push(...s)}if(c)o=h;else if(s=h.map(t=>t.toString()),0===s.length)break}}if(i)return o;const c=o[r<0?o.length+r:r];return void 0!==c?c:t}export{et as BinarySemaphore,d as ConfigFile,x as DefaultAllTextFiles,nt as DefaultAsyncSemaphoreCapacity,K as Deque,N as FilenameReservedRegex,Q as IntSet,ct as RateLimit,ot as Semaphore,ut as SignalGate,C as WindowsReservedNameRegex,W as arrayHasAll,G as extNameLevel,Et as extractCodeBlock,jt as extractTopLevelCodeBlocks,B as filenameReservedRegex,at as findPort,c as getMultiLevelExtname,b as glob,k as isStringIn,J as isValidFilename,L as isValidFilepath,F as normalizeIncludeFiles,dt as omitDeepBy,kt as omitEmptyDeep,At as parseCodeBlockSelector,y as parseFrontMatter,l as parseYaml,I as reControlCharsRegex,a as registerYamlTag,p as removeLeadingEmptyLines,U as sanitizeFilename,Z as sanitizeFilepath,V as sleep,m as stringifyYaml,O as toCamelCase,T as toCapitalCase,P as toPascalCase,S as traverseFolder,$ as traverseFolderSync,X as yieldExec};
+import{existsSync as t,mkdirSync as r,readFileSync as s,writeFileSync as n}from"fs";import i from"path";import{Config as e}from"load-config-file";import o from"path";function c(t,r=1){let s="";for(;r--;){const r=o.extname(t);if(!r)break;s=r+s,t=o.basename(t,r)}return s}import{parse as h,stringify as u}from"yaml";var f=[];function a(t){Array.isArray(t)||(t=[t]);for(const r of t){-1===f.indexOf(r)&&f.push(r)}}function l(t,r){if(r)if(r.customTags){if(Array.isArray(r.customTags))r.customTags=f.concat(r.customTags);else if("function"==typeof r.customTags){const t=r.customTags;r.customTags=r=>t(f.concat(r))}}else r.customTags=f;else r={customTags:f};return h(t,r)}function m(t,r){if(r)if(r.customTags){if(Array.isArray(r.customTags))r.customTags=f.concat(r.customTags);else if("function"==typeof r.customTags){const t=r.customTags;r.customTags=r=>t(f.concat(r))}}else r.customTags=f;else r={customTags:f};return u(t,r)}function p(t){const r=/^\s*(#[^\r\n]*)?[\r\n]+/;let s;for(;null!==(s=r.exec(t))&&((t=t.substring(s[0].length)).startsWith("\n")||t.startsWith("\r")||t.trimStart().startsWith("#")););return t}function y(t,r="---"){const s=r.length,n=p(t);if(n.startsWith(r)&&("\n"===n[r.length]||"\r"===n[r.length])){let t=n.indexOf("\n"+r,s);if(-1!==t){const i=n.slice(s,t);for(t+=r.length+1;"\n"===n[t]||"\r"===n[t];)t++;const e=n.slice(t);return{data:l(i)||{},content:e}}}return{data:{},content:t}}var d=class{static register(t,r,s){e.register(t,r),"string"==typeof t&&(t=[t]);for(const r of t)this.stringifys[r]=s}static loadSync(r,n){return function(r,{extLevel:n=1,externalFile:o}={}){r=g(r,n);let c=e.loadSync(r);if(!c&&o){if(!i.isAbsolute(o)){const t=i.dirname(r);o=i.join(t,o)}if(t(o)){const t=y(s(o,"utf8")).data;Object.keys(t).length&&(c=t)}}return c}(r,n)}static saveSync(s,e,o){return function(s,e,{extLevel:o=1}={}){const h=function(t,r=1){"."===t[0]&&r++;let s=c(t,r);(!s||s.split(".").length<=1)&&(t+=".yaml",s=".yaml");const n=new String(t);return n.extname=s,n}(s,o),u=h.extname;s=h.toString();const f=d.stringifys[u];if(!f)throw new Error(`${s} unsupported mime type: ${u}`);e=f(e);const a=i.dirname(s);t(a)||r(a,{recursive:!0});return n(s,e,{encoding:"utf8"}),s}(s,e,o)}static existsSync(t,r){return t=g(t,r?.extLevel),e.existsSync(t,r)}};function g(t,r=1){"."===t[0]&&r++;const s=c(t,r);return s&&s.split(".").length>1&&(t=t.slice(0,-s.length)),t}d.stringifys={},d.register([".yml",".yaml"],l,m),d.register([".json"],function(t){return JSON.parse(t)},t=>JSON.stringify(t,null,2));import{globMatch as w}from"@isdk/glob";import v from"path";function b(t,r,s){return s&&(t=v.relative(s,t)),w(t,r)}function k(t,r){return"string"==typeof r&&(r=[r]),-1!==r.indexOf(t)}var x=["**/*.((j|t)s?(x)|m(j|t)s)?(x)","**/*.(md|markdown|txt|?(x)htm?(l)|yaml|yml|xml|json|bat|sh|bash|zsh|ini|css|scss|less|sass|py|rb|php|go|java|c|cpp|h|hpp|hxx|rust|zig)"];function E(t,r=[]){if(t)if(Array.isArray(t))t=[...t];else{const s=t.include||[],n=t.exclude||[];0===s.length&&s.push(...r),t=[...s];for(const r of n)t.push(`!${r}`)}else t=[...r];return 0===t.length&&t.push(...r),t}import{readdir as A}from"fs/promises";import{readdirSync as j}from"fs";import F from"path";async function S(t,r){const s=await A(t,{withFileTypes:!0});for(const n of s){const s=F.join(t,n.name);try{if(n.isDirectory()){await r(s,n)||await S(s,r)}else{if(!0===await r(s,n))break}}catch(t){console.error(`Error processing file: ${s}`),console.error(t)}}}function P(t,r){const s=j(t,{withFileTypes:!0});for(const n of s){const s=F.join(t,n.name);try{if(n.isDirectory()){r(s,n)||S(s,r)}else{if(!0===r(s,n))break}}catch(t){console.error(`Error processing file: ${s}`),console.error(t)}}}function $(t){if(!t)return"";return t.replace(/[-_ ]+/g," ").split(" ").filter(Boolean).map(t=>{let r=t.charAt(0).toUpperCase();t=t.slice(1);let s=0;for(;/[A-Z]/.test(t[s]);)s++;return r+=s?t.slice(0,s).toLowerCase()+t.slice(s):t,r}).join("")}function M(t){return(t=$(t)).charAt(0).toLowerCase()+t.slice(1)}function N(t){if(!t)return"";return t.replace(/[-_ ]+/g," ").replace(/([a-z])([A-Z])/g,"$1 $2").split(" ").filter(Boolean).map(t=>t.charAt(0).toUpperCase()+t.slice(1).toLowerCase()).join(" ")}import O from"path";import{ErrorCode as R,throwError as T}from"@isdk/common-error";var z=/[<>:"/\\|?*\u0000-\u001F]/,C=/^(con|prn|aux|nul|com\d|lpt\d)$/i,D=/^\.+(\\|\/)|^\.+$/,_=/\.+$/,q=/[\u0000-\u001F\u0080-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/;function B(){return new RegExp(z.source,"g")}function I(){return new RegExp(q.source,"g")}function J(t){return t&&!(z.test(t)||I().test(t)||D.test(t)||_.test(t))}function L(t){const r=t.split(O.sep);return("/"===t[0]||r[0]&&O.dirname(r[0])===r[0])&&r.shift(),r.every(J)}function U(t,r={}){const s=r.replacement||"!";if((z.test(s)||q.test(s))&&T("Replacement string cannot contain reserved filename characters","sanitizeFilename",R.InvalidArgument),s.length>0){const r=/([<>:"/\\|?*\u0000-\u001F]){2,}/;t=t.replace(r,"$1")}if(t=(t=(t=(t=(t=t.normalize("NFD")).replace(D,s)).replace(B(),s)).replace(I(),s)).replace(_,""),s.length>0){"."===t[0]||"."!==t[0]||(t=s+t),"."===t[t.length-1]&&(t+=s)}t=C.test(t)?t+s:t;const n="number"==typeof r.maxLength?r.maxLength:100;if(t.length>n){const r=t.lastIndexOf(".");if(-1===r)t=t.slice(0,n);else{const s=t.slice(0,r),i=t.slice(r);t=s.slice(0,Math.max(1,n-i.length))+i}}return t}function Z(t,r={}){const s=t.split(O.sep);let n;("/"===t[0]||s[0]&&O.dirname(s[0])===s[0])&&(n=s.shift());const i=s.map(t=>U(t,r));return void 0!==n&&i.unshift(n),i.join(O.sep)}function G(t){return t.split(".").length-1}function W(t,r){const s=new Set(r),n=new Set;for(const r of t)if(s.has(r)&&(n.add(r),n.size===s.size))return!0;return n.size===s.size}function H(t=0){return r=Math.min(Math.max(16,t),1073741824),r>>>=0,r-=1,r|=r>>1,r|=r>>2,r|=r>>4,r|=r>>8,1+(r|=r>>16);var r}var K=class extends Array{constructor(t,r){Array.isArray(t)?(super(...t),this._length=t.length,t=void 0):(super(),this._length=0),this._capacity=H(t),this._front=0,this._disableAutoResize=r}push(t){let r=this._length;this.checkCapacity(r+1);const s=this._front+r&this._capacity-1;return this[s]=t,++r<=this._capacity&&(this._length=r),s}unshift(t){let r=this._length;this.checkCapacity(++r);const s=this._capacity,n=(this._front-1&s-1^s)-s;return this[n]=t,this._front=n,r<=this._capacity&&(this._length=r),n}pop(t){let r=this._length;if(0===r)return;let s=this._front+r-1&this._capacity-1,n=this[s];for(;--r>0&&t&&null==n;)s--,n=this[s];return this[s]=void 0,this._length=r,n}shift(t){let r=this._length;if(0===r)return;let s=this._front,n=this[s];for(;--r>0&&t&&null==n;)s=s+1&this._capacity-1,n=this[s];return this[s]=void 0,this._front=s+1&this._capacity-1,this._length=r,n}get size(){return this._length}get(t){let r;if(t===(0|t)){const s=this._length;t<0&&(t+=s),t>=0&&t<s&&(r=this[this._front+t&this._capacity-1])}return r}peekBack(){const t=this._length;if(0===t)return;return this[this._front+t-1&this._capacity-1]}peekFront(){if(0!==this._length)return this[this._front]}clear(){const t=this._length,r=this._front,s=this._capacity;for(let n=0;n<t;++n)this[r+n&s-1]=void 0;this._length=0,this._front=0}isEmpty(){return 0===this._length}removeAt(t){const r=this._length;if(t<0||t>=r)return;const s=this._front,n=this._capacity-1,i=s+t&n,e=this[i];if(t<r/2)this.copyWithin(s+1&n,s,s+t&n),this[s]=void 0,this._front=s+1&n;else{this.copyWithin(i,i+1&n,s+r&n);this[s+r-1&n]=void 0}return this._length=r-1,e}checkCapacity(t){this._capacity<t&&!this._disableAutoResize&&this.resizeTo(H(1.5*this._capacity+16))}resizeTo(t){const r=this._capacity;this._capacity=t;const s=this._front,n=this._length;if(s+n>r){!function(t,r,s,n,i){for(let e=0;e<i;++e)s[e+n]=t[e+r],t[e+r]=void 0}(this,0,this,r,s+n&r-1)}}},Q=class t{constructor(t=0){this.bitField=t}static has(t,r){return!!(t&1<<r)}static add(t,r){return t|1<<r}static delete(t,r){return t&~(1<<r)}add(t){return this.bitField|=1<<t,this}delete(t){return this.bitField&=~(1<<t),this}has(r){return t.has(this.bitField,r)}clear(){return this.bitField=0,this}valueOf(){return this.bitField}toString(){return this.bitField.toString()}toJSON(){return this.bitField}};async function V(t){return new Promise(r=>setTimeout(r,t))}async function X(){return new Promise(t=>{setImmediate(t)})}import{isAsync as Y}from"util-ex";import{EventEmitter as tt}from"events-ex";import{AbortError as rt}from"@isdk/common-error";var st=32;function nt(t){return"function"==typeof t}function it(){return"1"}var et=class{constructor(t={}){const{initFn:r=it,pauseFn:s,resumeFn:n,capacity:i=st}=t;if(nt(s)!==nt(n))throw new Error("pauseFn and resumeFn must be both set for pausing");this.waiting=new K(i),this.emitter=new tt,this.useDefaultTokens=r===it,this.pauseFn=s,this.resumeFn=n,this.initTokenFn=r,this.paused=!1,this._activeCount=0,this.initFree(t),this.init(t)}initFree(t){this.free=this.initTokenFn()}onReleased(t){const r=t?.token,s=this.waiting.shift(!0);s?this._dispatchTask(s,t):(this.resumeFn&&this.paused&&(this.paused=!1,this.resumeFn()),this.unlock(r))}init(t){this.emitter.on("release",t=>{this.onReleased(t)})}_newReleaser(t){let r=!1;const s=()=>{r||(r=!0,this.release(t))};return t&&Object.assign(s,t),s}_dispatchTask(t,r){const{resolve:s}=t;s(this._newReleaser(r))}lock(t){const r=this.free;if(r)return this.free=void 0,r}unlock(t){this.free=this.useDefaultTokens?"1":t??this.initTokenFn()}tryAcquire(t){return this.lock(t)}async acquire(t){this._activeCount++;const r=t?.signal,s=t=>{this.pauseFn&&!this.paused&&(this.paused=!0,this.pauseFn());const s=this.waiting.push(t),n=t.reject;return r&&r.addEventListener("abort",()=>{this.waiting[s]=void 0;const t=r.reason instanceof Error?r.reason:new rt(r.reason||"aborted");r.alreadyRejected=!0,n(t)}),s},n=this.tryAcquire(t),i=n&&Y(n),e=r=>new Promise((n,i)=>{const e={...t,resolve:n,reject:i,token:r};void 0===r?s(e):this._dispatchTask(e,{...t,token:r})});return i?n.then(t=>e(t)):e(n)}release(t){this._activeCount--,this.emitter.emit("release",t)}drain(){const t=[this.acquire()];return Promise.all(t)}abort(t){let r;for(;r=this.waiting.shift(!0);)r.reject(new rt(t))}get activeCount(){return this._activeCount}get pendingCount(){return this.waiting.size}},ot=class extends et{constructor(t,r){if("number"==typeof t)(r=r||{}).maxConcurrency=t;else if("number"!=typeof(r=t).maxConcurrency)throw new Error("maxConcurrency must be set");super(r),this.maxConcurrency=r.maxConcurrency,r.isReadyFn&&(this.isReady=r.isReadyFn)}initFree(t){const r=t.maxConcurrency=Math.max(1,t.maxConcurrency);this.free=new K(r);for(let t=0;t<r;t++)this.free.push(this.initTokenFn())}tryAcquire(t){let r=this.isReady;if(r&&Y(r)){return r instanceof Promise||(r=r()),r.then(r=>{if(r)return this.lock(t)})}if(!r||r())return this.lock(t)}unlock(t){this.free.push(this.useDefaultTokens?"1":t??this.initTokenFn())}lock(t){return this.free.pop()}drain(){const t=new Array(this.maxConcurrency);for(let r=0;r<this.maxConcurrency;r++)t[r]=this.acquire();return Promise.all(t)}};function ct(t,{timeUnit:r=1e3,uniformDistribution:s=!1}={}){const n=new ot(s?1:t),i=s?r/t:r;return async function(){await n.acquire(),setTimeout(()=>n.release(),i)}}import{AbortError as ht}from"@isdk/common-error";var ut=class{constructor(){this._isSignaled=!1,this.waitQueue=[]}get signaled(){return this._isSignaled}signal(t){if(this._isSignaled)return;this._isSignaled=!0,this._signalValue=t;const r=this.waitQueue.slice();for(this.waitQueue.length=0;r.length>0;){const t=r.shift();t?.resolve(this._signalValue)}}reset(){this._isSignaled=!1,this._signalValue=void 0,this.waitQueue.length=0}abort(t){if(this.waitQueue.length){const r=this.waitQueue.slice();this.waitQueue.length=0;const s=new ht(t);for(;r.length>0;){const{reject:t}=r.shift();t(s)}}}async wait(){return new Promise((t,r)=>{this._isSignaled?t(this._signalValue):this.waitQueue.push({resolve:t,reject:r})})}};import ft from"net";var at=Promise.resolve();async function lt(t,r){const s=await(at=at.catch(()=>{}).then(()=>async function(t,r){let s,n,i=10;"number"==typeof r?i=r:r&&"object"==typeof r&&(i=r.retryCount??10,s=r.host);if(void 0===t)n=0;else if(n="string"==typeof t?parseInt(t,10):Math.floor(t),n>=0||(n=0),n>65535)throw new Error("Port out of range: "+n);for(let t=0;t<=i;t++)try{return await mt(n,s)}catch(r){if(t===i)throw r;const s="EACCES"===r.code||"EPERM"===r.code,e="EADDRINUSE"===r.code;if(!s&&!e)throw r;if(s&&n<1024?n=1024:n++,n>65535)throw new Error("No available ports found up to 65535")}throw new Error("No available ports found")}(t,r)));return s}function mt(t,r){return new Promise((s,n)=>{const i=ft.createServer();i.unref(),i.on("error",t=>{i.close(()=>n(t))}),i.listen(t,r,()=>{const t=i.address().port;i.close(r=>{r?n(r):s(t)})})})}import{isEmpty as pt,isNil as yt,isObject as dt,isPlainObject as gt}from"lodash-es";function wt(t,r,s=new WeakMap){if(!dt(t)||yt(t))return t;if(s.has(t))return s.get(t);let n;if(Array.isArray(t)){n=[],s.set(t,n);const i=t.map(t=>wt(t,r,s)).filter((t,s)=>!r(t,s.toString()));return Object.assign(n,i),n.length>0?n:void 0}if(gt(t)){n={},s.set(t,n);const i=Reflect.ownKeys(t);for(const e of i){const i=wt(t[e],r,s);r(i,e)||(n[e]=i)}return pt(n)?void 0:n}return t}import{isArray as vt,isEmpty as bt,isNil as kt,isPlainObject as xt}from"lodash-es";var Et=(t,r)=>wt(t,t=>function(t){return!!kt(t)||"string"==typeof t&&0===t.trim().length||!(!vt(t)&&!xt(t))&&bt(t)}(t)||r&&"function"==typeof t),At={javascript:"js",jsx:"js",typescript:"ts",tsx:"ts",markdown:"md",python:"py",ruby:"rb",bash:"sh",zsh:"sh",shell:"sh",yaml:"yml",golang:"go",rust:"rs","c#":"cs",csharp:"cs","c++":"cpp"};function jt(t,r){if(!t)return t;const s=t.toLowerCase();return r&&s in r?r[s]:At[s]||s}function Ft(t,r={}){const{lang:s,langMap:n}=r,i=Array.isArray(s)?s.map(t=>jt(t,n)):s?[jt(s,n)]:s,e=/^[ \t]*(?<fence>`{3,}|~{3,})(?<lang>\S*)[ \t]*(?<meta>\S*?)\n(?<code>[\s\S]+?\n)?[ \t]*\k<fence>$/gm,o=[];let c;for(e.lastIndex=0;null!==(c=e.exec(t));){const t=c.groups?.lang?.toLowerCase();if(!i||i.includes(jt(t,n)??"")){const t=c.groups.code||"",r=new String(t);c.groups.lang&&(r.lang=c.groups.lang.toLowerCase()),c.groups.meta&&(r.meta=c.groups.meta),o.push(r)}}return o}function St(t){if(!t)return[];const r=[],s=/([>+~])?\s*([^\s>+~]+)/g;let n;if(Array.isArray(t))r.push({combinator:" ",lang:t});else for(;null!==(n=s.exec(t));){const t=n[1]||" ",s=n[2];r.push({combinator:t,lang:s})}return r}function Pt(t,r){const s=Array.isArray(r)||"string"==typeof r?{lang:r}:r??{},{index:n=-1,all:i}=s,e=St(s.lang);let o=[];if(0===e.length)o=Ft(t,s);else{let r=[t];for(let t=0;t<e.length;t++){const{combinator:n,lang:i}=e[t],c=t===e.length-1,h=[],u=0===t&&" "===n?">":n;for(const t of r){let r=[];switch(u){case">":r=Ft(t,{...s,lang:i,all:!0});break;case" ":console.warn('Descendant selector " " is not implemented yet.');break;case"+":console.warn('Adjacent sibling selector "+" is not implemented yet.');break;case"~":console.warn('General sibling selector "~" is not implemented yet.')}h.push(...r)}if(c)o=h;else if(r=h.map(t=>t.toString()),0===r.length)break}}if(i)return o;const c=o[n<0?o.length+n:n];return void 0!==c?c:t}export{et as BinarySemaphore,d as ConfigFile,x as DefaultAllTextFiles,st as DefaultAsyncSemaphoreCapacity,K as Deque,z as FilenameReservedRegex,Q as IntSet,ct as RateLimit,ot as Semaphore,ut as SignalGate,C as WindowsReservedNameRegex,W as arrayHasAll,G as extNameLevel,Pt as extractCodeBlock,Ft as extractTopLevelCodeBlocks,B as filenameReservedRegex,lt as findPort,c as getMultiLevelExtname,b as glob,k as isStringIn,J as isValidFilename,L as isValidFilepath,E as normalizeIncludeFiles,wt as omitDeepBy,Et as omitEmptyDeep,St as parseCodeBlockSelector,y as parseFrontMatter,l as parseYaml,I as reControlCharsRegex,a as registerYamlTag,p as removeLeadingEmptyLines,U as sanitizeFilename,Z as sanitizeFilepath,V as sleep,m as stringifyYaml,M as toCamelCase,N as toCapitalCase,$ as toPascalCase,S as traverseFolder,P as traverseFolderSync,X as yieldExec};

package/docs/classes/BinarySemaphore.md

@@ -6,35 +6,26 @@
 
 # Class: BinarySemaphore
 
-Defined in: [src/async-semaphore.ts:88](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L88)
+Defined in: [src/async-semaphore.ts:162](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L162)
 
-A binary semaphore implementation for managing concurrency in asynchronous operations.
-Unlike a general semaphore, a binary semaphore allows only one caller to acquire the semaphore at a time.
-It provides methods to acquire, release, and manage waiting tasks efficiently.
+二进制信号量（Binary Semaphore）实现。
+二进制信号量在任何时刻只允许一个调用方获取成功（类似于互斥锁）。
+它提供了获取（acquire）、释放（release）以及管理等待队列的机制，并支持背压控制（通过 pauseFn/resumeFn）。
 
-Example usage:
+示例用法：
 
 ```typescript
-const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
+const semaphore = new BinarySemaphore();
 
-const semaphore = new Semaphore(
-  4, // Allow 4 concurrent async calls
-  {
-    capacity: 100 // Prealloc space for 100 tokens
-  }
-);
-
-async function fetchData(x) {
-  await semaphore.acquire()
+async function performTask(data) {
+  const release = await semaphore.acquire();
   try {
-    console.log(semaphore.pendingCount + ' calls to fetch are waiting')
-    // ... do some async stuff with x
+    console.log('正在处理:', data);
+    // 执行异步操作...
   } finally {
-    semaphore.release();
+    release(); // 或者使用 semaphore.release();
   }
 }
-
-const data = await Promise.all(array.map(fetchData));
 ```
 
 ## Extended by
@@ -47,9 +38,9 @@ const data = await Promise.all(array.map(fetchData));
 
 > **new BinarySemaphore**(`options?`): `BinarySemaphore`
 
-Defined in: [src/async-semaphore.ts:145](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L145)
+Defined in: [src/async-semaphore.ts:188](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L188)
 
-Creates a binary semaphore object for managing concurrency in asynchronous operations.
+创建一个二进制信号量实例。
 
 #### Parameters
 
@@ -57,17 +48,25 @@ Creates a binary semaphore object for managing concurrency in asynchronous opera
 
 [`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md) = `{}`
 
+配置选项。
+
 #### Returns
 
 `BinarySemaphore`
 
+#### Throws
+
+如果只提供了 pauseFn 而未提供 resumeFn，或者反之，则抛出错误。
+
 ## Properties
 
 ### \_activeCount
 
 > `protected` **\_activeCount**: `number`
 
-Defined in: [src/async-semaphore.ts:97](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L97)
+Defined in: [src/async-semaphore.ts:180](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L180)
+
+记录当前活跃的（已获取但未释放）操作总数。
 
 ***
 
@@ -75,7 +74,9 @@ Defined in: [src/async-semaphore.ts:97](https://github.com/isdk/util.js/blob/227
 
 > `protected` **emitter**: `EventEmitter`
 
-Defined in: [src/async-semaphore.ts:91](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L91)
+Defined in: [src/async-semaphore.ts:168](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L168)
+
+内部事件触发器，用于协调释放和分发逻辑。
 
 ***
 
@@ -83,15 +84,19 @@ Defined in: [src/async-semaphore.ts:91](https://github.com/isdk/util.js/blob/227
 
 > `protected` **free**: `any`
 
-Defined in: [src/async-semaphore.ts:90](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L90)
+Defined in: [src/async-semaphore.ts:166](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L166)
+
+当前空闲的令牌。对于二进制信号量，只能持有一个令牌。
 
 ***
 
-### initTokenFn()
+### initTokenFn
 
 > `protected` **initTokenFn**: (`token?`) => `void`
 
-Defined in: [src/async-semaphore.ts:95](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L95)
+Defined in: [src/async-semaphore.ts:176](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L176)
+
+令牌初始化函数。
 
 #### Parameters
 
@@ -109,15 +114,19 @@ Defined in: [src/async-semaphore.ts:95](https://github.com/isdk/util.js/blob/227
 
 > `protected` **paused**: `boolean`
 
-Defined in: [src/async-semaphore.ts:96](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L96)
+Defined in: [src/async-semaphore.ts:178](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L178)
+
+记录当前是否处于暂停状态。
 
 ***
 
-### pauseFn()?
+### pauseFn?
 
-> `protected` `optional` **pauseFn**: () => `void`
+> `protected` `optional` **pauseFn?**: () => `void`
 
-Defined in: [src/async-semaphore.ts:93](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L93)
+Defined in: [src/async-semaphore.ts:172](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L172)
+
+获取积压时的暂停回调。
 
 #### Returns
 
@@ -125,11 +134,13 @@ Defined in: [src/async-semaphore.ts:93](https://github.com/isdk/util.js/blob/227
 
 ***
 
-### resumeFn()?
+### resumeFn?
+
+> `protected` `optional` **resumeFn?**: () => `void`
 
-> `protected` `optional` **resumeFn**: () => `void`
+Defined in: [src/async-semaphore.ts:174](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L174)
 
-Defined in: [src/async-semaphore.ts:94](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L94)
+恢复处理的回调。
 
 #### Returns
 
@@ -141,7 +152,9 @@ Defined in: [src/async-semaphore.ts:94](https://github.com/isdk/util.js/blob/227
 
 > `protected` **useDefaultTokens**: `boolean`
 
-Defined in: [src/async-semaphore.ts:92](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L92)
+Defined in: [src/async-semaphore.ts:170](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L170)
+
+标记是否使用默认的令牌初始化函数。
 
 ***
 
@@ -149,7 +162,9 @@ Defined in: [src/async-semaphore.ts:92](https://github.com/isdk/util.js/blob/227
 
 > `readonly` **waiting**: [`Deque`](Deque.md)\<[`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md) \| `undefined`\>
 
-Defined in: [src/async-semaphore.ts:89](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L89)
+Defined in: [src/async-semaphore.ts:164](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L164)
+
+存储等待获取令牌的任务队列。
 
 ## Accessors
 
@@ -159,19 +174,18 @@ Defined in: [src/async-semaphore.ts:89](https://github.com/isdk/util.js/blob/227
 
 > **get** **activeCount**(): `number`
 
-Defined in: [src/async-semaphore.ts:323](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L323)
-
-Get the total count of all active operations.
+Defined in: [src/async-semaphore.ts:430](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L430)
 
-This method returns the number of operations that are either:
-- Waiting in the queue to acquire the semaphore (`pendingCount`).
-- Already acquired the semaphore but have not yet released it.
+获取所有活跃操作的总数。
+包含：
+- 正在队列中等待获取信号量的操作（`pendingCount`）。
+- 已经成功获取信号量但尚未释放的操作。
 
 ##### Returns
 
 `number`
 
-The total count of active operations, including both waiting and ongoing tasks.
+活跃操作的总数。
 
 ***
 
@@ -181,15 +195,15 @@ The total count of active operations, including both waiting and ongoing tasks.
 
 > **get** **pendingCount**(): `number`
 
-Defined in: [src/async-semaphore.ts:332](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L332)
+Defined in: [src/async-semaphore.ts:439](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L439)
 
-Get the number of callers waiting on the semaphore, i.e. the number of pending promises.
+获取当前在等待队列中的调用方数量。
 
 ##### Returns
 
 `number`
 
-The number of waiters in the waiting list.
+等待中的 Promise 数量。
 
 ## Methods
 
@@ -197,7 +211,11 @@ The number of waiters in the waiting list.
 
 > **\_dispatchTask**(`task`, `options?`): `void`
 
-Defined in: [src/async-semaphore.ts:210](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L210)
+Defined in: [src/async-semaphore.ts:282](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L282)
+
+**`Internal`**
+
+将令牌分发给等待的任务。
 
 #### Parameters
 
@@ -205,10 +223,14 @@ Defined in: [src/async-semaphore.ts:210](https://github.com/isdk/util.js/blob/22
 
 [`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md)
 
+等待中的任务项。
+
 ##### options?
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放时传递的选项。
+
 #### Returns
 
 `void`
@@ -219,7 +241,12 @@ Defined in: [src/async-semaphore.ts:210](https://github.com/isdk/util.js/blob/22
 
 > **\_newReleaser**(`options?`): [`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
 
-Defined in: [src/async-semaphore.ts:195](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L195)
+Defined in: [src/async-semaphore.ts:260](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L260)
+
+**`Internal`**
+
+创建一个新的释放函数。
+确保释放逻辑只被执行一次，并携带相关的释放选项。
 
 #### Parameters
 
@@ -227,17 +254,24 @@ Defined in: [src/async-semaphore.ts:195](https://github.com/isdk/util.js/blob/22
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放选项。
+
 #### Returns
 
 [`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
 
+返回一个可调用的释放函数。
+
 ***
 
 ### abort()
 
 > **abort**(`reason?`): `void`
 
-Defined in: [src/async-semaphore.ts:306](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L306)
+Defined in: [src/async-semaphore.ts:414](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L414)
+
+中止所有正在等待的任务。
+所有在等待队列中的 Promise 将被拒绝并抛出 `AbortError`。
 
 #### Parameters
 
@@ -245,6 +279,8 @@ Defined in: [src/async-semaphore.ts:306](https://github.com/isdk/util.js/blob/22
 
 `any`
 
+中止的原因。
+
 #### Returns
 
 `void`
@@ -255,9 +291,18 @@ Defined in: [src/async-semaphore.ts:306](https://github.com/isdk/util.js/blob/22
 
 > **acquire**(`options?`): `Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
 
-Defined in: [src/async-semaphore.ts:244](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L244)
+Defined in: [src/async-semaphore.ts:339](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L339)
+
+获取信号量。
+如果信号量当前可用，将立即解析。否则，调用方将被加入等待队列，
+直到有令牌被释放。
 
-Acquire a token from the semaphore, thus decrement the number of available execution slots. If initFn is not used then the return value of the function can be discarded.
+逻辑流程：
+1. 增加活跃计数。
+2. 尝试通过 `tryAcquire` 立即获取令牌。
+3. 如果 `tryAcquire` 返回的是异步结果（通过 `isAsync` 判断），则等待其解析。
+4. 如果最终未获得令牌，则将任务推入 `waiting` 队列，并处理可选的 `AbortSignal`。
+5. 如果此时是队列中的第一个任务且定义了 `pauseFn`，则触发暂停回调。
 
 #### Parameters
 
@@ -265,11 +310,13 @@ Acquire a token from the semaphore, thus decrement the number of available execu
 
 [`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
+获取选项，可包含 `signal` 用于取消。
+
 #### Returns
 
 `Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
 
-A promise that resolves to a release function when a token is acquired. If the semaphore is full, the caller will be added to a waiting queue.
+解析为释放函数（`BinarySemaphoreReleaserFunc`）的 Promise。
 
 ***
 
@@ -277,21 +324,27 @@ A promise that resolves to a release function when a token is acquired. If the s
 
 > **drain**(): `Promise`\<`any`[]\>
 
-Defined in: [src/async-semaphore.ts:301](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L301)
+Defined in: [src/async-semaphore.ts:403](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L403)
 
-Drains the semaphore and returns all the initialized tokens in an array. Draining is an ideal way to ensure there are no pending async tasks, for example before a process will terminate.
+等待所有当前活跃的操作完成。
+它通过尝试获取一次信号量来确保之前的操作已经释放。
+在进程终止前使用此方法以确保没有挂起的异步任务。
 
 #### Returns
 
 `Promise`\<`any`[]\>
 
+解析为包含已获取令牌的数组的 Promise。
+
 ***
 
 ### init()
 
 > **init**(`options`): `void`
 
-Defined in: [src/async-semaphore.ts:189](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L189)
+Defined in: [src/async-semaphore.ts:246](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L246)
+
+初始化事件监听。在构造函数中被调用。
 
 #### Parameters
 
@@ -299,6 +352,8 @@ Defined in: [src/async-semaphore.ts:189](https://github.com/isdk/util.js/blob/22
 
 [`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md)
 
+配置选项。
+
 #### Returns
 
 `void`
@@ -309,7 +364,9 @@ Defined in: [src/async-semaphore.ts:189](https://github.com/isdk/util.js/blob/22
 
 > **initFree**(`options?`): `void`
 
-Defined in: [src/async-semaphore.ts:169](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L169)
+Defined in: [src/async-semaphore.ts:216](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L216)
+
+初始化空闲令牌。在构造函数中被调用。
 
 #### Parameters
 
@@ -317,6 +374,8 @@ Defined in: [src/async-semaphore.ts:169](https://github.com/isdk/util.js/blob/22
 
 [`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md)
 
+配置选项。
+
 #### Returns
 
 `void`
@@ -327,7 +386,9 @@ Defined in: [src/async-semaphore.ts:169](https://github.com/isdk/util.js/blob/22
 
 > **lock**(`options?`): `any`
 
-Defined in: [src/async-semaphore.ts:218](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L218)
+Defined in: [src/async-semaphore.ts:296](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L296)
+
+锁定信号量。尝试从空闲池中提取令牌。
 
 #### Parameters
 
@@ -335,17 +396,24 @@ Defined in: [src/async-semaphore.ts:218](https://github.com/isdk/util.js/blob/22
 
 [`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
+获取选项。
+
 #### Returns
 
 `any`
 
+如果有可用令牌则返回该令牌，否则返回 undefined。
+
 ***
 
 ### onReleased()
 
 > **onReleased**(`options?`): `void`
 
-Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L173)
+Defined in: [src/async-semaphore.ts:226](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L226)
+
+当信号量被释放时执行的内部处理逻辑。
+检查等待队列，如果有任务则分发令牌；否则将令牌归还至空闲池，并视情况调用 `resumeFn`。
 
 #### Parameters
 
@@ -353,6 +421,8 @@ Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/22
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放选项，可能包含令牌。
+
 #### Returns
 
 `void`
@@ -363,9 +433,11 @@ Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/22
 
 > **release**(`options?`): `void`
 
-Defined in: [src/async-semaphore.ts:293](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L293)
+Defined in: [src/async-semaphore.ts:391](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L391)
 
-Releases the semaphore, incrementing the number of free execution slots. If there are tasks in the waiting queue, the next task will be dispatched.
+释放信号量，增加可用执行槽位。
+如果等待队列中有任务，将触发下一个任务的执行。
+此方法会减少 `activeCount` 并发出 'release' 事件。
 
 #### Parameters
 
@@ -373,6 +445,8 @@ Releases the semaphore, incrementing the number of free execution slots. If ther
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放选项。
+
 #### Returns
 
 `void`
@@ -383,9 +457,10 @@ Releases the semaphore, incrementing the number of free execution slots. If ther
 
 > **tryAcquire**(`options?`): `any`
 
-Defined in: [src/async-semaphore.ts:235](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L235)
+Defined in: [src/async-semaphore.ts:320](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L320)
 
-Attempt to acquire a token from the semaphore, if one is available immediately. Otherwise, return undefined.
+尝试立即获取令牌。
+如果信号量当前不可用，则立即返回 `undefined` 而不进入等待队列。
 
 #### Parameters
 
@@ -393,11 +468,13 @@ Attempt to acquire a token from the semaphore, if one is available immediately.
 
 [`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
+获取选项。
+
 #### Returns
 
 `any`
 
-Returns a token if the semaphore is not full; otherwise, returns `undefined`.
+如果获取成功则返回令牌，否则返回 `undefined`。
 
 ***
 
@@ -405,7 +482,9 @@ Returns a token if the semaphore is not full; otherwise, returns `undefined`.
 
 > **unlock**(`token?`): `void`
 
-Defined in: [src/async-semaphore.ts:226](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/async-semaphore.ts#L226)
+Defined in: [src/async-semaphore.ts:309](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L309)
+
+解锁信号量。将令牌归还至空闲池。
 
 #### Parameters
 
@@ -413,6 +492,8 @@ Defined in: [src/async-semaphore.ts:226](https://github.com/isdk/util.js/blob/22
 
 `any`
 
+要归还的令牌。如果未提供，则使用初始化函数生成。
+
 #### Returns
 
 `void`

package/docs/classes/ConfigFile.md

@@ -6,7 +6,7 @@
 
 # Class: ConfigFile
 
-Defined in: [src/config-file.ts:46](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/config-file.ts#L46)
+Defined in: [src/config-file.ts:46](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/config-file.ts#L46)
 
 Represents a configuration file utility class that provides methods to load and save configuration files.
 It supports multiple file formats such as YAML, JSON, etc., by registering corresponding parsers and stringifiers.
@@ -45,7 +45,7 @@ console.log(config); // Output: { key: 'value' }
 
 > `static` **stringifys**: `Record`\<`string`, [`StringifyFunc`](../type-aliases/StringifyFunc.md)\> = `{}`
 
-Defined in: [src/config-file.ts:50](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/config-file.ts#L50)
+Defined in: [src/config-file.ts:50](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/config-file.ts#L50)
 
 A record of registered stringify functions for different file extensions.
 
@@ -55,7 +55,7 @@ A record of registered stringify functions for different file extensions.
 
 > `static` **existsSync**(`filename`, `options?`): `boolean`
 
-Defined in: [src/config-file.ts:142](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/config-file.ts#L142)
+Defined in: [src/config-file.ts:142](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/config-file.ts#L142)
 
 Checks if a configuration file exists at the specified path.
 
@@ -104,7 +104,7 @@ console.log(existsWithExt); // true or false
 
 > `static` **loadSync**(`filename`, `options?`): `any`
 
-Defined in: [src/config-file.ts:91](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/config-file.ts#L91)
+Defined in: [src/config-file.ts:91](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/config-file.ts#L91)
 
 Loads a configuration file based on the provided filename and options.
 
@@ -141,7 +141,7 @@ console.log(config); // Output: { key: 'value' }
 
 > `static` **register**(`extname`, `parser`, `stringify`): `void`
 
-Defined in: [src/config-file.ts:64](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/config-file.ts#L64)
+Defined in: [src/config-file.ts:64](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/config-file.ts#L64)
 
 Registers a parser and stringifier for specific file extensions.
 
@@ -149,9 +149,9 @@ Registers a parser and stringifier for specific file extensions.
 
 ##### extname
 
-The file extension(s) to register the parser and stringifier for.
+`string` \| `string`[]
 
-`string` | `string`[]
+The file extension(s) to register the parser and stringifier for.
 
 ##### parser
 
@@ -181,7 +181,7 @@ ConfigFile.register(['.json'], JSON.parse, (obj) => JSON.stringify(obj, null, 2)
 
 > `static` **saveSync**(`filename`, `config`, `options?`): `string`
 
-Defined in: [src/config-file.ts:108](https://github.com/isdk/util.js/blob/2279f0b4363625d4cd214e9bab0415d49b594498/src/config-file.ts#L108)
+Defined in: [src/config-file.ts:108](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/config-file.ts#L108)
 
 Saves a configuration object to a file with the specified filename and options.