@cnstra/core 2.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @cnstra/core
 
-**Graph-routed, type-safe orchestration for reactive apps — no global event bus.**
+**Workflow / orchestration engine for TypeScript — deterministic, embeddable, in-memory.**
 
 📚 **[Full Documentation →](https://cnstra.org/)** | [Quick Start](https://cnstra.org/docs/core/quick-start) | [API Reference](https://cnstra.org/docs/core/api) | [Recipes](https://cnstra.org/docs/recipes)
 
@@ -10,6 +10,10 @@
 
 **Zero dependencies** • **No pub/sub** • **CNS approach** (Central Neural Network of your app)
 
+Common backend use-cases:
+- **Jobs** (queues/workers), **sync/integrations** (webhooks), **ETL/pipelines**
+- **Retries/timeouts/cancellation** and **saga-style compensations**
+
 👉 **[Read the full documentation →](https://cnstra.org/)**
 
 ## Quick Start

package/dist/CNSPersistOptionsRegistry.d.ts

@@ -0,0 +1,22 @@
+import { CNSCollateral } from './CNSCollateral';
+import { CNSStimulation } from './CNSStimulation';
+import { TCNSAxon } from './types/TCNSAxon';
+import { TCNSNeuron } from './types/TCNSNeuron';
+import { TCNSCollateralPersistOptions, TCNSNeuronPersistOptions, TCNSStimulationPersistOptions } from './types/TCNSPersist';
+export declare class CNSPersistOptionsRegistry {
+    private neurons;
+    private neuronNames;
+    private collaterals;
+    private stimulations;
+    addNeuron(neuron: TCNSNeuron<unknown, TCNSAxon>, options: TCNSNeuronPersistOptions<TCNSNeuron<unknown, TCNSAxon>>): void;
+    getNeuron(name: string): TCNSNeuron<unknown, TCNSAxon> | undefined;
+    getNeuronName(neuron: TCNSNeuron<unknown, TCNSAxon>): string | undefined;
+    removeNeuron(name: string): void;
+    addCollateral(collateral: CNSCollateral<unknown>, options: TCNSCollateralPersistOptions): void;
+    getCollateral(name: string): CNSCollateral<unknown> | undefined;
+    removeCollateral(name: string): void;
+    addStimulation(stimulation: CNSStimulation<TCNSNeuron<unknown, TCNSAxon>>, options: TCNSStimulationPersistOptions): void;
+    getStimulation(stimulationId: string): CNSStimulation<TCNSNeuron<unknown, TCNSAxon>> | undefined;
+    removeStimulation(stimulationId: string): void;
+}
+//# sourceMappingURL=CNSPersistOptionsRegistry.d.ts.map

package/dist/CNSPersistOptionsRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CNSPersistOptionsRegistry.d.ts","sourceRoot":"","sources":["../src/CNSPersistOptionsRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACH,4BAA4B,EAC5B,wBAAwB,EACxB,6BAA6B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,qBAAa,yBAAyB;IAClC,OAAO,CAAC,OAAO,CAAoD;IACnE,OAAO,CAAC,WAAW,CAAwD;IAE3E,OAAO,CAAC,WAAW,CAA6C;IAEhE,OAAO,CAAC,YAAY,CAGhB;IAEJ,SAAS,CACL,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EACrC,OAAO,EAAE,wBAAwB,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,GACjE,IAAI;IAKP,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,SAAS;IAIlE,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,MAAM,GAAG,SAAS;IAIxE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMhC,aAAa,CACT,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,EAClC,OAAO,EAAE,4BAA4B,GACtC,IAAI;IAIP,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS;IAI/D,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC,cAAc,CACV,WAAW,EAAE,cAAc,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,EAC1D,OAAO,EAAE,6BAA6B,GACvC,IAAI;IAIP,cAAc,CACV,aAAa,EAAE,MAAM,GACtB,cAAc,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,GAAG,SAAS;IAI5D,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;CAGjD"}

package/dist/CNSStimulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CNSStimulation.d.ts","sourceRoot":"","sources":["../src/CNSStimulation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CNSStimulation.d.ts","sourceRoot":"","sources":["../src/CNSStimulation.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -957,6 +957,55 @@ var CNSCollateral = class {
   }
 };
 
+// src/utils/CNSDrainGuard.ts
+var CNSDrainGuard = class {
+  constructor(guardOptions) {
+    this.guardOptions = guardOptions;
+  }
+  isDraining() {
+    return this.currentDrain !== void 0;
+  }
+  getCurrentStimulation() {
+    return this.currentStimulation;
+  }
+  drain() {
+    if (this.currentDrain) return this.currentDrain;
+    const stimulation = this.guardOptions.cns.stimulate(
+      this.guardOptions.signal,
+      this.createStimulationOptions()
+    );
+    const drain = stimulation.waitUntilComplete().finally(() => {
+      if (this.currentDrain !== drain) return;
+      this.currentDrain = void 0;
+      this.currentStimulation = void 0;
+      this.currentAbortController = void 0;
+    });
+    this.currentStimulation = stimulation;
+    this.currentDrain = drain;
+    return drain;
+  }
+  abort(reason) {
+    if (!this.currentAbortController) return false;
+    if (this.currentAbortController.signal.aborted) return false;
+    this.currentAbortController.abort(reason);
+    return true;
+  }
+  createStimulationOptions() {
+    const options = this.guardOptions.options;
+    if (options?.abortSignal) {
+      return options;
+    }
+    if (typeof AbortController === "undefined") {
+      return options ?? {};
+    }
+    this.currentAbortController = new AbortController();
+    return {
+      ...options,
+      abortSignal: this.currentAbortController.signal
+    };
+  }
+};
+
 // src/factory/index.ts
 var collateral = () => new CNSCollateral();
 var neuron = (axon) => {
@@ -1102,6 +1151,7 @@ var modality = (afferentPaths) => {
 
 exports.CNS = CNS;
 exports.CNSCollateral = CNSCollateral;
+exports.CNSDrainGuard = CNSDrainGuard;
 exports.CNSStimulationContextStore = CNSStimulationContextStore;
 exports.afferentPath = afferentPath;
 exports.collateral = collateral;