@univer-cli/generic-keyed-instance-pool 1.0.0-beta.2

package/README.md

@@ -0,0 +1,83 @@
+# @univer-cli/generic-keyed-instance-pool
+
+English | [简体中文](./README.zh-CN.md)
+
+Create, exclusively lease, cache, and recycle stateful instances by an opaque key supplied by the application.
+
+It is intended for objects that are expensive to create, reused by key, restricted to one caller at a time, and explicitly destroyed, such as browsers, database sessions, or headless runtimes. Stateless objects and objects that can be shared safely across concurrent callers do not need this pool.
+
+## Installation
+
+```bash
+pnpm add @univer-cli/generic-keyed-instance-pool
+```
+
+Requires Node.js 22.12 or higher.
+
+## Quick Start
+
+```ts
+import {
+  createGenericKeyedInstancePool,
+  type ManagedInstanceFactory,
+} from "@univer-cli/generic-keyed-instance-pool";
+
+interface Client {
+  close(): Promise<void>;
+  query(): Promise<string>;
+}
+
+const factory: ManagedInstanceFactory<Client, { url: string }> = {
+  async create({ init }) {
+    return createClient(init.url);
+  },
+  async destroy({ instance }) {
+    await instance.close();
+  },
+};
+
+const pool = createGenericKeyedInstancePool({
+  factory,
+  cache: {
+    idleTtlMs: 60_000,
+    maxEntries: 20,
+  },
+});
+
+const lease = await pool.acquire({
+  key: "server-a",
+  init: { url: "https://example.com" },
+});
+
+try {
+  console.log(await lease.instance.query());
+} catch (error) {
+  await lease.invalidate();
+  throw error;
+} finally {
+  await lease.release();
+}
+
+await pool.close();
+```
+
+## Lifecycle guarantees
+
+- The first creation for a key is single-flight, preventing duplicate instances from being created concurrently.
+- An instance is only handed over to one lease at a time.
+- Callers waiting for the same key acquire the lease in FIFO order.
+- After normal release, the instance can enter the idle cache.
+- Invalidation marks an instance as unsafe to reuse, so it is destroyed during release.
+- TTL and LRU only recycle idle instances and do not interrupt active leases.
+- `close()` rejects new acquisitions, waits for or terminates remaining lifecycle work, and destroys cached instances.
+
+The key is used only for equality checks and events; the package never interprets it. The caller must ensure that a key always maps to compatible initialization data. The pool does not define the application's target-to-key algorithm.
+
+## Failures and observability
+
+Create, destroy, wait-cancellation, and pool-close failures are exposed as `InstancePoolError`. Event callbacks provide visibility into creation, acquisition, release, eviction, and destruction without exposing the internal cache.
+
+## Responsibility boundaries
+
+This package provides only the in-process lifecycle for raw instances. It does not provide workers, IPC, RPC, method proxies, business operations, or cross-process sharing. For collaboration runtimes hosted in workers, use
+`@univer-cli/univer-collaboration-runtime-pool`.

package/README.zh-CN.md

@@ -0,0 +1,87 @@
+# @univer-cli/generic-keyed-instance-pool
+
+[English](./README.md) | 简体中文
+
+按 application 提供的 opaque key 创建、独占租用、缓存和回收有状态 instance。
+
+它适合创建成本高、需要按 key 复用、同一时间只能被一个调用方使用且必须显式销毁的对象，例如 browser、
+database session 或 headless runtime。若对象无状态或可安全并发共享，不需要使用这个 pool。
+
+## 安装
+
+```bash
+pnpm add @univer-cli/generic-keyed-instance-pool
+```
+
+要求 Node.js 22.12 或更高版本。
+
+## 快速开始
+
+```ts
+import {
+  createGenericKeyedInstancePool,
+  type ManagedInstanceFactory,
+} from "@univer-cli/generic-keyed-instance-pool";
+
+interface Client {
+  close(): Promise<void>;
+  query(): Promise<string>;
+}
+
+const factory: ManagedInstanceFactory<Client, { url: string }> = {
+  async create({ init }) {
+    return createClient(init.url);
+  },
+  async destroy({ instance }) {
+    await instance.close();
+  },
+};
+
+const pool = createGenericKeyedInstancePool({
+  factory,
+  cache: {
+    idleTtlMs: 60_000,
+    maxEntries: 20,
+  },
+});
+
+const lease = await pool.acquire({
+  key: "server-a",
+  init: { url: "https://example.com" },
+});
+
+try {
+  console.log(await lease.instance.query());
+} catch (error) {
+  await lease.invalidate();
+  throw error;
+} finally {
+  await lease.release();
+}
+
+await pool.close();
+```
+
+## 生命周期保证
+
+- 同一个 key 的首次创建使用 single-flight，不会并行创建重复 instance。
+- 一个 instance 同一时刻只交给一个 lease。
+- 等待同一 key 的 acquire 按 FIFO 顺序获得 lease。
+- 正常 release 后 instance 可以进入 idle cache。
+- invalidate 表示 instance 已不可安全复用，会在 release 时销毁。
+- TTL 和 LRU 只回收 idle instance，不中断 active lease。
+- `close()` 拒绝新的 acquire，等待或终止剩余 lifecycle，并销毁缓存内容。
+
+Key 只用于相等性与事件，不会被 package 解释。调用方必须保证同一 key 对应兼容的 init；pool 不替 application
+定义 target-to-key 算法。
+
+## 失败与可观测性
+
+Create、destroy、等待取消和 pool close 失败会以 `InstancePoolError` 暴露。可通过 event callback 观察创建、
+acquire、release、eviction 和 destroy，而无需读取内部 cache。
+
+## 职责边界
+
+这是纯进程内 raw instance lifecycle。Package 不提供 worker、IPC、RPC、方法代理、业务 operation 或跨进程
+共享。需要 worker 中的 collaboration runtime 时，使用
+`@univer-cli/univer-collaboration-runtime-pool`。

package/dist/index.cjs

@@ -0,0 +1 @@
+'use strict';module['exports']=require('./index.mjs');

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+//#region src/errors.d.ts
+type InstancePoolErrorCode = "INSTANCE_POOL_CAPACITY_EXCEEDED" | "INSTANCE_POOL_CLOSED" | "INSTANCE_POOL_INVALID_INPUT";
+declare class InstancePoolError extends Error {
+  readonly code: string;
+  constructor(code: InstancePoolErrorCode | string, message: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/types.d.ts
+interface InstanceAcquireInput<TInit> {
+  /** Opaque cache identity owned by the application. */
+  readonly key: string;
+  /** Used only when the pool must create a new instance. */
+  readonly init: TInit;
+}
+interface ManagedInstanceInput<TInstance> {
+  readonly instance: TInstance;
+  readonly key: string;
+}
+interface ManagedInstanceFactory<TInstance, TInit> {
+  create(input: InstanceAcquireInput<TInit>): Promise<TInstance>;
+  destroy(input: ManagedInstanceInput<TInstance>): Promise<void>;
+}
+interface InstanceLease<TInstance> {
+  readonly instance: TInstance;
+  readonly key: string;
+  /** Ends the exclusive lease and allows the instance to be reused. */
+  release(): Promise<void>;
+  /** Ends the exclusive lease and permanently removes the instance from the pool. */
+  invalidate(): Promise<void>;
+}
+interface KeyedInstancePool<TInstance, TInit> {
+  acquire(input: InstanceAcquireInput<TInit>): Promise<InstanceLease<TInstance>>;
+  close(): Promise<void>;
+}
+interface InstancePoolCacheOptions {
+  readonly idleTtlMs?: number;
+  readonly maxEntries?: number;
+}
+type InstancePoolEvent = {
+  readonly key: string;
+  readonly type: "create-start";
+} | {
+  readonly durationMs: number;
+  readonly key: string;
+  readonly type: "create-complete";
+} | {
+  readonly key: string;
+  readonly type: "cache-hit";
+} | {
+  readonly key: string;
+  readonly reason: "invalidate" | "lru" | "ttl";
+  readonly type: "evicted";
+};
+interface GenericKeyedInstancePoolOptions<TInstance, TInit> {
+  readonly cache?: InstancePoolCacheOptions;
+  readonly factory: ManagedInstanceFactory<TInstance, TInit>;
+  readonly onEvent?: (event: InstancePoolEvent) => void;
+}
+//#endregion
+//#region src/keyed-instance-pool.d.ts
+declare function createGenericKeyedInstancePool<TInstance, TInit>(options: GenericKeyedInstancePoolOptions<TInstance, TInit>): KeyedInstancePool<TInstance, TInit>;
+//#endregion
+export { type GenericKeyedInstancePoolOptions, type InstanceAcquireInput, type InstanceLease, type InstancePoolCacheOptions, InstancePoolError, type InstancePoolErrorCode, type InstancePoolEvent, type KeyedInstancePool, type ManagedInstanceFactory, type ManagedInstanceInput, createGenericKeyedInstancePool };

package/dist/index.mjs

@@ -0,0 +1 @@
+function _0x5dd4(_0x28ea46,_0x41c348){_0x28ea46=_0x28ea46-0xa3;const _0x34cb04=_0x34cb();let _0x5dd437=_0x34cb04[_0x28ea46];return _0x5dd437;}const _0x232c74=_0x5dd4;(function(_0x10d0c2,_0x2fa539){const _0x2ae9ed=_0x5dd4,_0x127dca=_0x10d0c2();while(!![]){try{const _0x378d94=-parseInt(_0x2ae9ed(0xb2))/0x1+-parseInt(_0x2ae9ed(0xbc))/0x2*(-parseInt(_0x2ae9ed(0xe1))/0x3)+parseInt(_0x2ae9ed(0xb1))/0x4+-parseInt(_0x2ae9ed(0xe0))/0x5*(-parseInt(_0x2ae9ed(0xac))/0x6)+-parseInt(_0x2ae9ed(0xc9))/0x7*(-parseInt(_0x2ae9ed(0xd6))/0x8)+-parseInt(_0x2ae9ed(0xd2))/0x9+parseInt(_0x2ae9ed(0xb3))/0xa;if(_0x378d94===_0x2fa539)break;else _0x127dca['push'](_0x127dca['shift']());}catch(_0x1c4a66){_0x127dca['push'](_0x127dca['shift']());}}}(_0x34cb,0x65cad));var e=class extends Error{[_0x232c74(0xa6)];constructor(_0x4c5530,_0x578837,_0x5608cf){const _0xb5469e=_0x232c74;super(_0x578837,_0x5608cf),this[_0xb5469e(0xdf)]=_0xb5469e(0xc5),this[_0xb5469e(0xa6)]=_0x4c5530;}},t=0x493e0,n=0x14;function r(_0x54fa67){const _0x43e4dd=_0x232c74;let _0x255ceb=new Map(),_0x4d2391=new Set(),_0x2facbf=new Map(),_0x1b7cd4=_0x54fa67[_0x43e4dd(0xb6)]?.[_0x43e4dd(0xdc)]??t,_0x37813c=_0x54fa67['cache']?.[_0x43e4dd(0xaf)]??n,_0x3afb32=!0x1,_0x42fb1c,_0x2d76c0=0x0;i(_0x1b7cd4,_0x37813c);let _0x4881da={async 'acquire'(_0x920ca2){const _0x5b84a4=_0x43e4dd;_0x43c22e(),a(_0x920ca2);let _0x242a1d=_0x255ceb['get'](_0x920ca2[_0x5b84a4(0xd0)]);if(_0x242a1d)return _0x242a1d[_0x5b84a4(0xa5)]?await o(_0x920ca2,_0x242a1d[_0x5b84a4(0xc2)]):(c(_0x242a1d),_0x242a1d['busy']=!0x0,_0x14fd0e({'key':_0x920ca2['key'],'type':_0x5b84a4(0xd5)}),_0x79cdaa(_0x920ca2['key'],_0x242a1d));let _0x156871=_0x2facbf[_0x5b84a4(0xab)](_0x920ca2[_0x5b84a4(0xd0)]);if(_0x156871)return await o(_0x920ca2,_0x156871);let _0x1d4e91,_0xa1ba0c=new Promise(_0x23ea9c=>{_0x1d4e91=_0x23ea9c;});_0x4d2391[_0x5b84a4(0xde)](_0xa1ba0c),_0x2facbf[_0x5b84a4(0xd8)](_0x920ca2[_0x5b84a4(0xd0)],[]);let _0x3b14fe=Date[_0x5b84a4(0xba)]();_0x14fd0e({'key':_0x920ca2['key'],'type':_0x5b84a4(0xd1)});try{await _0x272a11();let _0x4df960=await _0x54fa67[_0x5b84a4(0xca)][_0x5b84a4(0xae)](_0x920ca2);if(_0x3afb32)throw await _0x54fa67['factory']['destroy']({'instance':_0x4df960,'key':_0x920ca2['key']}),l();let _0x12d236={'busy':!0x0,'closed':!0x1,'instance':_0x4df960,'invalidated':!0x1,'lastIdleSequence':0x0,'waiters':_0x2facbf[_0x5b84a4(0xab)](_0x920ca2[_0x5b84a4(0xd0)])??[]};return _0x255ceb[_0x5b84a4(0xd8)](_0x920ca2[_0x5b84a4(0xd0)],_0x12d236),_0x14fd0e({'durationMs':Date['now']()-_0x3b14fe,'key':_0x920ca2[_0x5b84a4(0xd0)],'type':'create-complete'}),_0x79cdaa(_0x920ca2[_0x5b84a4(0xd0)],_0x12d236);}catch(_0x32fa5d){throw s(_0x2facbf[_0x5b84a4(0xab)](_0x920ca2[_0x5b84a4(0xd0)])??[],_0x32fa5d),_0x32fa5d;}finally{_0x2facbf[_0x5b84a4(0xaa)](_0x920ca2['key']),_0x4d2391[_0x5b84a4(0xaa)](_0xa1ba0c),_0x1d4e91();}},async 'close'(){if(_0x42fb1c)return await _0x42fb1c;_0x3afb32=!0x0,_0x42fb1c=_0x3f51d5(),await _0x42fb1c;}};return _0x4881da;function _0x79cdaa(_0x1b5cc7,_0x2e1949){const _0x364ca0=_0x43e4dd;let _0x1b9c46=!0x1;return{'instance':_0x2e1949[_0x364ca0(0xc7)],'key':_0x1b5cc7,async 'invalidate'(){const _0x4d700f=_0x364ca0;_0x1b9c46||(_0x1b9c46=!0x0,_0x2e1949[_0x4d700f(0xb0)]=!0x0,await _0x31a3ac(_0x1b5cc7,_0x2e1949,_0x4d700f(0xb7)));},async 'release'(){const _0x2dcf7d=_0x364ca0;if(_0x1b9c46||(_0x1b9c46=!0x0,_0x2e1949['closed']))return;if(_0x2e1949[_0x2dcf7d(0xb0)]){await _0x31a3ac(_0x1b5cc7,_0x2e1949,_0x2dcf7d(0xb7));return;}let _0x26c8d4=_0x2e1949[_0x2dcf7d(0xc2)][_0x2dcf7d(0xbe)]();_0x26c8d4?_0x26c8d4[_0x2dcf7d(0xd9)](_0x79cdaa(_0x1b5cc7,_0x2e1949)):(_0x2e1949[_0x2dcf7d(0xa5)]=!0x1,_0x2e1949[_0x2dcf7d(0xd7)]=++_0x2d76c0,_0x5bfc1a(_0x1b5cc7,_0x2e1949));}};}async function _0x31a3ac(_0x45f21f,_0x5d2d05,_0x4c7856){const _0x17e669=_0x43e4dd;let _0x3918ed=_0x5d2d05[_0x17e669(0xc2)][_0x17e669(0xcb)](0x0);_0x255ceb[_0x17e669(0xab)](_0x45f21f)===_0x5d2d05&&_0x255ceb['delete'](_0x45f21f);try{await _0x584b87(_0x45f21f,_0x5d2d05);}finally{_0x4c7856&&_0x14fd0e({'key':_0x45f21f,'reason':_0x4c7856,'type':'evicted'}),_0x3afb32?s(_0x3918ed,l()):_0x2aa0f7(_0x3918ed);}}function _0x5bfc1a(_0x45ad52,_0x237de4){const _0x44e373=_0x43e4dd;c(_0x237de4),_0x237de4[_0x44e373(0xbd)]=setTimeout(()=>{const _0x5d3ca5=_0x44e373;_0x237de4[_0x5d3ca5(0xa5)]||_0x255ceb[_0x5d3ca5(0xab)](_0x45ad52)!==_0x237de4||(_0x255ceb[_0x5d3ca5(0xaa)](_0x45ad52),_0x584b87(_0x45ad52,_0x237de4)[_0x5d3ca5(0xc0)](()=>_0x14fd0e({'key':_0x45ad52,'reason':_0x5d3ca5(0xb4),'type':_0x5d3ca5(0xbb)}))[_0x5d3ca5(0xa8)](()=>void 0x0));},_0x1b7cd4),_0x237de4[_0x44e373(0xbd)][_0x44e373(0xce)]?.();}async function _0x272a11(){const _0x44e473=_0x43e4dd;for(;_0x255ceb[_0x44e473(0xc4)]+_0x2facbf[_0x44e473(0xc4)]>_0x37813c;){let _0x9301e7;for(let _0x2157e1 of _0x255ceb)_0x2157e1[0x1][_0x44e473(0xa5)]||(!_0x9301e7||_0x2157e1[0x1][_0x44e473(0xd7)]<_0x9301e7[0x1][_0x44e473(0xd7)])&&(_0x9301e7=_0x2157e1);if(!_0x9301e7)throw new e(_0x44e473(0xa7),'Instance\x20pool\x20capacity\x20'+_0x37813c+_0x44e473(0xdd));_0x255ceb[_0x44e473(0xaa)](_0x9301e7[0x0]),await _0x584b87(_0x9301e7[0x0],_0x9301e7[0x1]),_0x14fd0e({'key':_0x9301e7[0x0],'reason':_0x44e473(0xd3),'type':_0x44e473(0xbb)});}}async function _0x3f51d5(){const _0x204039=_0x43e4dd;let _0x48b8ec=l(),_0x44305c=[..._0x255ceb[_0x204039(0xb9)]()];for(let [,_0x1753c7]of _0x44305c)s(_0x1753c7[_0x204039(0xc2)],_0x48b8ec);for(let _0x449801 of _0x2facbf[_0x204039(0xad)]())s(_0x449801,_0x48b8ec);_0x255ceb[_0x204039(0xcc)]();let _0x1c0be7=(await Promise[_0x204039(0xda)]([..._0x44305c['map'](async([_0x12b775,_0x4de96a])=>await _0x584b87(_0x12b775,_0x4de96a)),..._0x4d2391]))['find'](_0x1e33d1=>_0x1e33d1[_0x204039(0xbf)]==='rejected');if(_0x1c0be7?.[_0x204039(0xbf)]===_0x204039(0xb5))throw _0x1c0be7[_0x204039(0xc3)];}function _0x14fd0e(_0x13c4a9){try{_0x54fa67['onEvent']?.(_0x13c4a9);}catch{}}function _0x43c22e(){if(_0x3afb32)throw l();}function _0x2aa0f7(_0x4985f1){const _0x2ab025=_0x43e4dd;for(let _0x4ac014 of _0x4985f1)_0x4881da[_0x2ab025(0xb8)](_0x4ac014[_0x2ab025(0xcd)])[_0x2ab025(0xc0)](_0x4ac014[_0x2ab025(0xd9)],_0x4ac014[_0x2ab025(0xc8)]);}async function _0x584b87(_0x88665d,_0x921720){const _0x25274b=_0x43e4dd;_0x921720['closed']||(_0x921720[_0x25274b(0xa9)]=!0x0,c(_0x921720),await _0x54fa67[_0x25274b(0xca)][_0x25274b(0xa4)]({'instance':_0x921720[_0x25274b(0xc7)],'key':_0x88665d}));}}function i(_0x3c4746,_0x266327){const _0x5226dd=_0x232c74;if(!Number[_0x5226dd(0xc1)](_0x3c4746)||_0x3c4746<0x0)throw new e(_0x5226dd(0xcf),_0x5226dd(0xc6));if(!Number[_0x5226dd(0xe2)](_0x266327)||_0x266327<=0x0)throw new e(_0x5226dd(0xcf),_0x5226dd(0xa3));}function a(_0x198913){const _0x579c15=_0x232c74;if(_0x198913[_0x579c15(0xd0)][_0x579c15(0xd4)]===0x0)throw new e('INSTANCE_POOL_INVALID_INPUT','key\x20must\x20not\x20be\x20empty');}function o(_0x323a15,_0x4023a5){return new Promise((_0x22bcba,_0x1a378f)=>{const _0x1cab82=_0x5dd4;_0x4023a5[_0x1cab82(0xdb)]({'input':_0x323a15,'reject':_0x1a378f,'resolve':_0x22bcba});});}function s(_0x336f40,_0x2d2b1e){for(let _0x1ae6fe of _0x336f40['splice'](0x0))_0x1ae6fe['reject'](_0x2d2b1e);}function _0x34cb(){const _0x4be0c4=['idleTtlMs','\x20is\x20occupied\x20by\x20active\x20or\x20loading\x20instances','add','name','85455EdvSMx','6TrAzSR','isSafeInteger','cache.maxEntries\x20must\x20be\x20a\x20positive\x20integer','destroy','busy','code','INSTANCE_POOL_CAPACITY_EXCEEDED','catch','closed','delete','get','78BUErGd','values','create','maxEntries','invalidated','3047192UnXLtm','719539rQOLnT','5137900oVecat','ttl','rejected','cache','invalidate','acquire','entries','now','evicted','153462gYgNKf','idleTimer','shift','status','then','isFinite','waiters','reason','size','InstancePoolError','cache.idleTtlMs\x20must\x20be\x20a\x20finite\x20non-negative\x20number','instance','reject','161uOtzwM','factory','splice','clear','input','unref','INSTANCE_POOL_INVALID_INPUT','key','create-start','5305113nCWjYF','lru','length','cache-hit','25984BqWTJh','lastIdleSequence','set','resolve','allSettled','push'];_0x34cb=function(){return _0x4be0c4;};return _0x34cb();}function c(_0x2abb34){const _0x8f7e94=_0x232c74;_0x2abb34[_0x8f7e94(0xbd)]!==void 0x0&&(clearTimeout(_0x2abb34[_0x8f7e94(0xbd)]),delete _0x2abb34[_0x8f7e94(0xbd)]);}function l(){return new e('INSTANCE_POOL_CLOSED','Instance\x20pool\x20is\x20closed');}export{e as InstancePoolError,r as createGenericKeyedInstancePool};

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@univer-cli/generic-keyed-instance-pool",
+  "type": "module",
+  "version": "1.0.0-beta.2",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md"
+  ]
+}