@danypops/vehicle-core 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-watchers.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-watchers.js";

package/dist/vehicle-watchers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * "Watch a changing resource, get notified" -- lifted near-verbatim from
+ * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
+ * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
+ * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
+ * Confirmed independently reinvented three-plus times across this house's
+ * own ecosystem before this existed: Lector's own registry, Lector's CLI
+ * (a second, non-resilient reimplementation of the same watch/subscribe
+ * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
+ * ensurePushChannel()+poll dance independently).
+ *
+ * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
+ * I/O here. Matching pattern/resource against a real changed resource is a
+ * provider's own job, not this registry's; this only tracks which topic a
+ * given (scope, resource) pair publishes under, and bounds how many watches
+ * one scope can accumulate.
+ */
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export declare const DEFAULT_MAX_WATCHES_PER_SCOPE = 32;
+export interface WatchRegistration {
+    readonly watchId: string;
+    readonly scope: string;
+    readonly resource: string;
+    readonly topic: string;
+}
+/** Raised when a scope already has its configured maximum of registrations -- fails closed, the same bounded-resource discipline every other Vehicle capability already applies, rather than letting one scope accumulate unbounded watch state. */
+export declare class WatchLimitExceeded extends Error {
+    readonly scope: string;
+    readonly max: number;
+    constructor(scope: string, max: number);
+}
+export interface WatchRegistryOptions {
+    /** Defaults to DEFAULT_MAX_WATCHES_PER_SCOPE. */
+    readonly maxWatchesPerScope?: number;
+}
+export declare class WatchRegistry {
+    private readonly byId;
+    private readonly byScope;
+    private readonly maxWatchesPerScope;
+    constructor(options?: WatchRegistryOptions);
+    add(scope: string, resource: string, watchId: string, topic: string): WatchRegistration;
+    /** The removed registration, or undefined if watchId was already unknown -- idempotent, like the rest of Vehicle's own unregister-shaped operations. Returns the registration itself (not just a boolean) so a caller can tell which scope lost its last watch without a separate lookup. */
+    remove(watchId: string): WatchRegistration | undefined;
+    /** False once a scope has zero remaining registrations -- a provider's own signal to release whatever underlying watch/subscription resource that scope was backing. */
+    hasAnyFor(scope: string): boolean;
+    registrationsFor(scope: string): readonly WatchRegistration[];
+}
+/**
+ * The wire topic name a watch's changes publish under -- one shared naming
+ * function so a provider's publish() call and a subscriber's connectPushChannel()
+ * topic can never drift apart, the same role vehicleEventTopic() plays for
+ * Vehicle Events' own declared, fixed-schema event types. Deliberately a
+ * separate function/namespace from vehicleEventTopic(): a watch's topic is
+ * per-watch-instance-dynamic (one new topic per watchId), not a small fixed
+ * set of declared event types, so it doesn't fit Vehicle Events' own
+ * name@version schema-declaration model -- it reuses the same PushChannel
+ * transport substrate Vehicle Events made available generically, not the
+ * declared-event-type layer itself.
+ */
+export declare function vehicleWatchTopic(watchId: string): string;

package/dist/vehicle-watchers.js

@@ -0,0 +1,85 @@
+/**
+ * "Watch a changing resource, get notified" -- lifted near-verbatim from
+ * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
+ * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
+ * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
+ * Confirmed independently reinvented three-plus times across this house's
+ * own ecosystem before this existed: Lector's own registry, Lector's CLI
+ * (a second, non-resilient reimplementation of the same watch/subscribe
+ * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
+ * ensurePushChannel()+poll dance independently).
+ *
+ * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
+ * I/O here. Matching pattern/resource against a real changed resource is a
+ * provider's own job, not this registry's; this only tracks which topic a
+ * given (scope, resource) pair publishes under, and bounds how many watches
+ * one scope can accumulate.
+ */
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export const DEFAULT_MAX_WATCHES_PER_SCOPE = 32;
+/** Raised when a scope already has its configured maximum of registrations -- fails closed, the same bounded-resource discipline every other Vehicle capability already applies, rather than letting one scope accumulate unbounded watch state. */
+export class WatchLimitExceeded extends Error {
+    scope;
+    max;
+    constructor(scope, max) {
+        super(`scope "${scope}" already has ${max} active watches -- unwatch one before adding another`);
+        this.scope = scope;
+        this.max = max;
+        this.name = "WatchLimitExceeded";
+    }
+}
+export class WatchRegistry {
+    byId = new Map();
+    byScope = new Map();
+    maxWatchesPerScope;
+    constructor(options = {}) {
+        this.maxWatchesPerScope = options.maxWatchesPerScope ?? DEFAULT_MAX_WATCHES_PER_SCOPE;
+    }
+    add(scope, resource, watchId, topic) {
+        const existing = this.byScope.get(scope) ?? new Set();
+        if (existing.size >= this.maxWatchesPerScope)
+            throw new WatchLimitExceeded(scope, this.maxWatchesPerScope);
+        const registration = { watchId, scope, resource, topic };
+        existing.add(watchId);
+        this.byScope.set(scope, existing);
+        this.byId.set(watchId, registration);
+        return registration;
+    }
+    /** The removed registration, or undefined if watchId was already unknown -- idempotent, like the rest of Vehicle's own unregister-shaped operations. Returns the registration itself (not just a boolean) so a caller can tell which scope lost its last watch without a separate lookup. */
+    remove(watchId) {
+        const registration = this.byId.get(watchId);
+        if (!registration)
+            return undefined;
+        this.byId.delete(watchId);
+        const scopeWatches = this.byScope.get(registration.scope);
+        scopeWatches?.delete(watchId);
+        if (scopeWatches?.size === 0)
+            this.byScope.delete(registration.scope);
+        return registration;
+    }
+    /** False once a scope has zero remaining registrations -- a provider's own signal to release whatever underlying watch/subscription resource that scope was backing. */
+    hasAnyFor(scope) {
+        return (this.byScope.get(scope)?.size ?? 0) > 0;
+    }
+    registrationsFor(scope) {
+        const ids = this.byScope.get(scope);
+        if (!ids)
+            return [];
+        return Array.from(ids, (id) => this.byId.get(id)).filter((registration) => registration !== undefined);
+    }
+}
+/**
+ * The wire topic name a watch's changes publish under -- one shared naming
+ * function so a provider's publish() call and a subscriber's connectPushChannel()
+ * topic can never drift apart, the same role vehicleEventTopic() plays for
+ * Vehicle Events' own declared, fixed-schema event types. Deliberately a
+ * separate function/namespace from vehicleEventTopic(): a watch's topic is
+ * per-watch-instance-dynamic (one new topic per watchId), not a small fixed
+ * set of declared event types, so it doesn't fit Vehicle Events' own
+ * name@version schema-declaration model -- it reuses the same PushChannel
+ * transport substrate Vehicle Events made available generically, not the
+ * declared-event-type layer itself.
+ */
+export function vehicleWatchTopic(watchId) {
+    return `vehicle-watch:${watchId}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./atomic-json.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-watchers.js";

package/src/vehicle-watchers.ts

@@ -0,0 +1,103 @@
+/**
+ * "Watch a changing resource, get notified" -- lifted near-verbatim from
+ * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
+ * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
+ * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
+ * Confirmed independently reinvented three-plus times across this house's
+ * own ecosystem before this existed: Lector's own registry, Lector's CLI
+ * (a second, non-resilient reimplementation of the same watch/subscribe
+ * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
+ * ensurePushChannel()+poll dance independently).
+ *
+ * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
+ * I/O here. Matching pattern/resource against a real changed resource is a
+ * provider's own job, not this registry's; this only tracks which topic a
+ * given (scope, resource) pair publishes under, and bounds how many watches
+ * one scope can accumulate.
+ */
+
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export const DEFAULT_MAX_WATCHES_PER_SCOPE = 32;
+
+export interface WatchRegistration {
+	readonly watchId: string;
+	readonly scope: string;
+	readonly resource: string;
+	readonly topic: string;
+}
+
+/** Raised when a scope already has its configured maximum of registrations -- fails closed, the same bounded-resource discipline every other Vehicle capability already applies, rather than letting one scope accumulate unbounded watch state. */
+export class WatchLimitExceeded extends Error {
+	constructor(
+		readonly scope: string,
+		readonly max: number,
+	) {
+		super(`scope "${scope}" already has ${max} active watches -- unwatch one before adding another`);
+		this.name = "WatchLimitExceeded";
+	}
+}
+
+export interface WatchRegistryOptions {
+	/** Defaults to DEFAULT_MAX_WATCHES_PER_SCOPE. */
+	readonly maxWatchesPerScope?: number;
+}
+
+export class WatchRegistry {
+	private readonly byId = new Map<string, WatchRegistration>();
+	private readonly byScope = new Map<string, Set<string>>();
+	private readonly maxWatchesPerScope: number;
+
+	constructor(options: WatchRegistryOptions = {}) {
+		this.maxWatchesPerScope = options.maxWatchesPerScope ?? DEFAULT_MAX_WATCHES_PER_SCOPE;
+	}
+
+	add(scope: string, resource: string, watchId: string, topic: string): WatchRegistration {
+		const existing = this.byScope.get(scope) ?? new Set();
+		if (existing.size >= this.maxWatchesPerScope) throw new WatchLimitExceeded(scope, this.maxWatchesPerScope);
+		const registration: WatchRegistration = { watchId, scope, resource, topic };
+		existing.add(watchId);
+		this.byScope.set(scope, existing);
+		this.byId.set(watchId, registration);
+		return registration;
+	}
+
+	/** The removed registration, or undefined if watchId was already unknown -- idempotent, like the rest of Vehicle's own unregister-shaped operations. Returns the registration itself (not just a boolean) so a caller can tell which scope lost its last watch without a separate lookup. */
+	remove(watchId: string): WatchRegistration | undefined {
+		const registration = this.byId.get(watchId);
+		if (!registration) return undefined;
+		this.byId.delete(watchId);
+		const scopeWatches = this.byScope.get(registration.scope);
+		scopeWatches?.delete(watchId);
+		if (scopeWatches?.size === 0) this.byScope.delete(registration.scope);
+		return registration;
+	}
+
+	/** False once a scope has zero remaining registrations -- a provider's own signal to release whatever underlying watch/subscription resource that scope was backing. */
+	hasAnyFor(scope: string): boolean {
+		return (this.byScope.get(scope)?.size ?? 0) > 0;
+	}
+
+	registrationsFor(scope: string): readonly WatchRegistration[] {
+		const ids = this.byScope.get(scope);
+		if (!ids) return [];
+		return Array.from(ids, (id) => this.byId.get(id)).filter(
+			(registration): registration is WatchRegistration => registration !== undefined,
+		);
+	}
+}
+
+/**
+ * The wire topic name a watch's changes publish under -- one shared naming
+ * function so a provider's publish() call and a subscriber's connectPushChannel()
+ * topic can never drift apart, the same role vehicleEventTopic() plays for
+ * Vehicle Events' own declared, fixed-schema event types. Deliberately a
+ * separate function/namespace from vehicleEventTopic(): a watch's topic is
+ * per-watch-instance-dynamic (one new topic per watchId), not a small fixed
+ * set of declared event types, so it doesn't fit Vehicle Events' own
+ * name@version schema-declaration model -- it reuses the same PushChannel
+ * transport substrate Vehicle Events made available generically, not the
+ * declared-event-type layer itself.
+ */
+export function vehicleWatchTopic(watchId: string): string {
+	return `vehicle-watch:${watchId}`;
+}