@nextclaw/shared 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+import { NcpEndpointEvent, NcpSessionSummary } from "@nextclaw/ncp";
+
+//#region src/types/typed-key.types.d.ts
+type TypedKey<T = unknown> = {
+  readonly id: string;
+  readonly _type?: T;
+};
+type Key<T = unknown> = TypedKey<T> | string;
+declare function createTypedKey<T>(id: string): TypedKey<T>;
+declare function getKeyId(key: Key<unknown>): string;
+//#endregion
+//#region src/types/event-bus.types.d.ts
+type EventKey<T> = TypedKey<T>;
+type EventSource = string;
+type EventEnvelope<T = unknown> = {
+  type: string;
+  payload: T;
+  emittedAt?: string;
+  source?: EventSource;
+};
+type EventEmitOptions = {
+  emittedAt?: string;
+  source?: EventSource;
+};
+type EventHandler<T> = (payload: T, envelope: EventEnvelope<T>) => void;
+type Unsubscribe = () => void;
+type EventBusOptions = {
+  onFirstSubscriber?: () => void;
+  onListenerError?: (params: {
+    type: string;
+    payload: unknown;
+    error: unknown;
+  }) => void;
+  onNoSubscribers?: () => void;
+};
+type AppEventKey<T> = Key<T>;
+type AppEventSource = EventSource;
+type AppEventEnvelope<T = unknown> = EventEnvelope<T>;
+type AppEventEmitOptions = EventEmitOptions;
+type AppEventHandler<T> = EventHandler<T>;
+type AppEvent = AppEventEnvelope;
+//#endregion
+//#region src/services/event-bus.service.d.ts
+declare class EventBus {
+  private readonly listeners;
+  private readonly globalListeners;
+  private listenerCount;
+  private readonly onFirstSubscriber?;
+  private readonly onListenerError?;
+  private readonly onNoSubscribers?;
+  constructor(options?: EventBusOptions);
+  emit: <T>(key: Key<T>, payload: T, options?: AppEventEmitOptions) => void;
+  emitEnvelope: <T>(event: AppEventEnvelope<T>) => void;
+  on: <T>(key: AppEventKey<T>, handler: AppEventHandler<T>) => Unsubscribe;
+  off: <T>(key: AppEventKey<T>, handler: AppEventHandler<T>) => void;
+  once: <T>(key: AppEventKey<T>, handler: AppEventHandler<T>) => Unsubscribe;
+  subscribeAll: (handler: (event: AppEventEnvelope) => void) => Unsubscribe;
+  private registerSubscriber;
+  private unregisterSubscriber;
+  private safeInvokeListener;
+  private safeInvokeGlobalListener;
+}
+//#endregion
+//#region src/services/ingress.service.d.ts
+type IngressEnvelope<TPayload = unknown> = {
+  type: Key<TPayload>;
+  payload?: TPayload;
+  source?: string;
+};
+type IngressContext = {
+  source: string;
+  token?: string | null;
+};
+type IngressHandler<TPayload = unknown, TResult = unknown> = (envelope: IngressEnvelope<TPayload>, context: IngressContext) => Promise<TResult> | TResult;
+declare class Ingress {
+  private readonly handlers;
+  readonly addHandler: <TPayload = unknown, TResult = unknown>(type: Key<TPayload>, handler: IngressHandler<TPayload, TResult>) => (() => void);
+  readonly handle: <TPayload = unknown, TResult = unknown>(envelope: IngressEnvelope<TPayload>, context: IngressContext) => Promise<TResult>;
+}
+//#endregion
+//#region src/services/disposable.service.d.ts
+type Cleanup = () => void;
+type Disposable = {
+  dispose: () => void;
+};
+declare const toDisposable: (dispose: Cleanup) => Disposable;
+declare abstract class DisposableOwner implements Disposable {
+  protected readonly cleanups: Cleanup[];
+  private disposed;
+  protected get isDisposed(): boolean;
+  protected addCleanup: (cleanup: Cleanup) => Cleanup;
+  protected addDisposable: <T extends Disposable>(disposable: T) => T;
+  dispose: () => void;
+}
+declare class DisposableStore implements Disposable {
+  private readonly disposables;
+  private isDisposed;
+  add: <T extends Disposable>(disposable: T) => T;
+  clear: () => void;
+  dispose: () => void;
+}
+//#endregion
+//#region src/types/update.types.d.ts
+type UpdateStatus = "idle" | "checking" | "update-available" | "downloading" | "downloaded" | "applying" | "restart-required" | "up-to-date" | "blocked" | "failed";
+type InstallationKind = "desktop-bundle" | "npm-runtime-bundle" | "npm-global" | "unknown";
+type UpdateBlockReason = "host-too-old" | "unsupported-installation" | "signature-verification-unavailable";
+type UpdateProgress = {
+  downloadedBytes: number;
+  totalBytes: number | null;
+  percent: number | null;
+};
+type UpdatePreferences = {
+  automaticChecks: boolean;
+  autoDownload: boolean;
+};
+type UpdateSnapshot = {
+  status: UpdateStatus;
+  installationKind: InstallationKind;
+  channel: "stable" | "beta";
+  hostVersion: string | null;
+  currentVersion: string | null;
+  availableVersion: string | null;
+  downloadedVersion: string | null;
+  minimumHostVersion: string | null;
+  releaseNotesUrl: string | null;
+  lastCheckedAt: string | null;
+  progress: UpdateProgress | null;
+  canAutoDownload: boolean;
+  canApplyInApp: boolean;
+  requiresRestart: boolean;
+  blockReason: UpdateBlockReason | null;
+  recoveryCommand: string | null;
+  errorMessage: string | null;
+  preferences: UpdatePreferences;
+};
+//#endregion
+//#region src/configs/event-keys.config.d.ts
+declare function createEventKey<T>(id: string): EventKey<T>;
+declare function createAppEventKey<T>(id: string): AppEventKey<T>;
+declare const eventKeys: {
+  readonly configUpdated: AppEventKey<{
+    path: string;
+  }>;
+  readonly channelConfigApplyStatus: AppEventKey<{
+    channel: string;
+    status: "started" | "succeeded" | "failed";
+    message?: string;
+  }>;
+  readonly sessionUpdated: AppEventKey<{
+    sessionKey: string;
+  }>;
+  readonly sessionRunStatus: AppEventKey<{
+    sessionKey: string;
+    status: "running" | "idle";
+  }>;
+  readonly ncpEvent: AppEventKey<NcpEndpointEvent>;
+  readonly sessionSummaryUpsert: AppEventKey<{
+    summary: NcpSessionSummary;
+  }>;
+  readonly sessionSummaryDelete: AppEventKey<{
+    sessionKey: string;
+  }>;
+  readonly configReloadStarted: AppEventKey<Record<string, unknown> | undefined>;
+  readonly configReloadFinished: AppEventKey<Record<string, unknown> | undefined>;
+  readonly error: AppEventKey<{
+    message: string;
+    code?: string;
+  }>;
+  readonly connectionOpen: AppEventKey<Record<string, never> | undefined>;
+  readonly connectionClose: AppEventKey<Record<string, never> | undefined>;
+  readonly connectionError: AppEventKey<{
+    message?: string;
+  } | undefined>;
+  readonly runtimeUpdateSnapshot: AppEventKey<UpdateSnapshot>;
+};
+//#endregion
+export { type AppEvent, type AppEventEmitOptions, type AppEventEnvelope, type AppEventHandler, type AppEventKey, type AppEventSource, type Cleanup, type Disposable, DisposableOwner, DisposableStore, EventBus, type EventBusOptions, type EventEmitOptions, type EventEnvelope, type EventHandler, type EventKey, type EventSource, Ingress, type IngressContext, type IngressEnvelope, type IngressHandler, type InstallationKind, type Key, type TypedKey, type Unsubscribe, type UpdateBlockReason, type UpdatePreferences, type UpdateProgress, type UpdateSnapshot, type UpdateStatus, createAppEventKey, createEventKey, createTypedKey, eventKeys, getKeyId, toDisposable };

package/dist/index.js

@@ -0,0 +1,220 @@
+//#region src/types/typed-key.types.ts
+function createTypedKey(id) {
+	const normalizedId = id.trim();
+	if (!normalizedId) throw new Error("typed key id is required");
+	return { id: normalizedId };
+}
+function getKeyId(key) {
+	return typeof key === "string" ? key.trim() : key.id;
+}
+//#endregion
+//#region src/services/event-bus.service.ts
+var EventBus = class {
+	listeners = /* @__PURE__ */ new Map();
+	globalListeners = /* @__PURE__ */ new Set();
+	listenerCount = 0;
+	onFirstSubscriber;
+	onListenerError;
+	onNoSubscribers;
+	constructor(options = {}) {
+		this.onFirstSubscriber = options.onFirstSubscriber;
+		this.onListenerError = options.onListenerError;
+		this.onNoSubscribers = options.onNoSubscribers;
+	}
+	emit = (key, payload, options = {}) => {
+		const envelope = {
+			type: getKeyId(key),
+			payload,
+			...options.emittedAt ? { emittedAt: options.emittedAt } : {},
+			...options.source ? { source: options.source } : {}
+		};
+		this.emitEnvelope(envelope);
+	};
+	emitEnvelope = (event) => {
+		const listeners = this.listeners.get(event.type);
+		if (listeners) for (const listener of listeners) this.safeInvokeListener(event, listener);
+		if (this.globalListeners.size === 0) return;
+		for (const listener of this.globalListeners) this.safeInvokeGlobalListener(event, listener);
+	};
+	on = (key, handler) => {
+		const keyId = getKeyId(key);
+		const listeners = this.listeners.get(keyId) ?? /* @__PURE__ */ new Set();
+		const typedHandler = handler;
+		const added = !listeners.has(typedHandler);
+		listeners.add(typedHandler);
+		this.listeners.set(keyId, listeners);
+		if (added) this.registerSubscriber();
+		return () => {
+			this.off(key, handler);
+		};
+	};
+	off = (key, handler) => {
+		const keyId = getKeyId(key);
+		const listeners = this.listeners.get(keyId);
+		if (!listeners) return;
+		const deleted = listeners.delete(handler);
+		if (listeners.size === 0) this.listeners.delete(keyId);
+		if (deleted) this.unregisterSubscriber();
+	};
+	once = (key, handler) => {
+		const wrappedHandler = (payload, envelope) => {
+			unsubscribe();
+			handler(payload, envelope);
+		};
+		const unsubscribe = this.on(key, wrappedHandler);
+		return unsubscribe;
+	};
+	subscribeAll = (handler) => {
+		const added = !this.globalListeners.has(handler);
+		this.globalListeners.add(handler);
+		if (added) this.registerSubscriber();
+		return () => {
+			if (this.globalListeners.delete(handler)) this.unregisterSubscriber();
+		};
+	};
+	registerSubscriber = () => {
+		this.listenerCount += 1;
+		if (this.listenerCount === 1) this.onFirstSubscriber?.();
+	};
+	unregisterSubscriber = () => {
+		this.listenerCount = Math.max(0, this.listenerCount - 1);
+		if (this.listenerCount === 0) this.onNoSubscribers?.();
+	};
+	safeInvokeListener = (event, listener) => {
+		try {
+			listener(event.payload, event);
+		} catch (error) {
+			this.onListenerError?.({
+				type: event.type,
+				payload: event.payload,
+				error
+			});
+		}
+	};
+	safeInvokeGlobalListener = (event, listener) => {
+		try {
+			listener(event);
+		} catch (error) {
+			this.onListenerError?.({
+				type: event.type,
+				payload: event.payload,
+				error
+			});
+		}
+	};
+};
+//#endregion
+//#region src/services/ingress.service.ts
+var Ingress = class {
+	handlers = /* @__PURE__ */ new Map();
+	addHandler = (type, handler) => {
+		const normalizedType = getKeyId(type);
+		if (!normalizedType) throw new Error("ingress type is required");
+		this.handlers.set(normalizedType, handler);
+		return () => {
+			if (this.handlers.get(normalizedType) === handler) this.handlers.delete(normalizedType);
+		};
+	};
+	handle = async (envelope, context) => {
+		const normalizedType = getKeyId(envelope.type);
+		const handler = this.handlers.get(normalizedType);
+		if (!handler) throw new Error(`Unsupported ingress type: ${normalizedType}`);
+		return await handler(envelope, context);
+	};
+};
+//#endregion
+//#region src/services/disposable.service.ts
+const once = (cleanup) => {
+	let disposed = false;
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		cleanup();
+	};
+};
+const runCleanups = (cleanups) => {
+	const errors = [];
+	for (const cleanup of cleanups) try {
+		cleanup();
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to run cleanups.");
+};
+const toDisposable = (dispose) => ({ dispose: once(dispose) });
+var DisposableOwner = class {
+	cleanups = [];
+	disposed = false;
+	get isDisposed() {
+		return this.disposed;
+	}
+	addCleanup = (cleanup) => {
+		const disposableCleanup = once(cleanup);
+		if (this.disposed) {
+			disposableCleanup();
+			return disposableCleanup;
+		}
+		this.cleanups.push(disposableCleanup);
+		return disposableCleanup;
+	};
+	addDisposable = (disposable) => {
+		this.addCleanup(() => {
+			disposable.dispose();
+		});
+		return disposable;
+	};
+	dispose = () => {
+		if (this.disposed) return;
+		this.disposed = true;
+		runCleanups(this.cleanups.splice(0).reverse());
+	};
+};
+var DisposableStore = class {
+	disposables = /* @__PURE__ */ new Set();
+	isDisposed = false;
+	add = (disposable) => {
+		if (this.isDisposed) {
+			disposable.dispose();
+			return disposable;
+		}
+		this.disposables.add(disposable);
+		return disposable;
+	};
+	clear = () => {
+		const current = [...this.disposables];
+		this.disposables.clear();
+		for (const disposable of current.reverse()) disposable.dispose();
+	};
+	dispose = () => {
+		if (this.isDisposed) return;
+		this.isDisposed = true;
+		this.clear();
+	};
+};
+//#endregion
+//#region src/configs/event-keys.config.ts
+function createEventKey(id) {
+	return createTypedKey(id);
+}
+function createAppEventKey(id) {
+	return createTypedKey(id);
+}
+const eventKeys = {
+	configUpdated: createAppEventKey("config.updated"),
+	channelConfigApplyStatus: createAppEventKey("channel.config.apply-status"),
+	sessionUpdated: createAppEventKey("session.updated"),
+	sessionRunStatus: createAppEventKey("session.run-status"),
+	ncpEvent: createAppEventKey("ncp.event"),
+	sessionSummaryUpsert: createAppEventKey("session.summary.upsert"),
+	sessionSummaryDelete: createAppEventKey("session.summary.delete"),
+	configReloadStarted: createAppEventKey("config.reload.started"),
+	configReloadFinished: createAppEventKey("config.reload.finished"),
+	error: createAppEventKey("error"),
+	connectionOpen: createAppEventKey("connection.open"),
+	connectionClose: createAppEventKey("connection.close"),
+	connectionError: createAppEventKey("connection.error"),
+	runtimeUpdateSnapshot: createAppEventKey("runtime.update.snapshot")
+};
+//#endregion
+export { DisposableOwner, DisposableStore, EventBus, Ingress, createAppEventKey, createEventKey, createTypedKey, eventKeys, getKeyId, toDisposable };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@nextclaw/shared",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Shared lightweight primitives and contracts for NextClaw packages.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nextclaw/ncp": "0.5.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension",
+    "lint": "eslint src --max-warnings=0",
+    "test": "vitest run",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}