@danypops/vehicle-core 0.18.0 → 0.18.2

package/dist/concurrency/debounced-scheduler.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Coalesces a burst of calls for the same key into exactly one callback fire,
+ * delayMs after the last call for that key -- the classic debounce shape,
+ * useful anywhere a flurry of raw upstream events for one logical unit of
+ * work (a filesystem save that fires more than once via temp-file write +
+ * atomic rename, a burst of webhook deliveries for the same resource) needs
+ * to collapse into a single downstream action. Different keys are fully
+ * independent. Pure timer bookkeeping, no I/O -- the callback itself does
+ * whatever real work is needed.
+ */
+/** The minimal logging surface this module needs -- any real Logger (e.g. Vehicle's own daemon Logger) satisfies this structurally, no adapter required. */
+export interface MinimalLogger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+}
+export declare class DebounceCapacityExceeded extends Error {
+    readonly key: string;
+    readonly max: number;
+    constructor(key: string, max: number);
+}
+export interface DebouncedSchedulerOptions {
+    /** Maximum distinct keys with a pending fire at once. Default 4096. */
+    readonly maxKeys?: number;
+    readonly logger?: MinimalLogger;
+}
+export declare class DebouncedScheduler {
+    private readonly timers;
+    private readonly delayMs;
+    private readonly maxKeys;
+    private readonly logger;
+    constructor(delayMs: number, options?: DebouncedSchedulerOptions);
+    /**
+     * Schedules `callback` to run delayMs after this call, resetting any pending fire already
+     * scheduled for `key`. A callback that throws or rejects is caught and dropped -- there is
+     * no request awaiting this fire to report the error, and an unhandled timer failure would
+     * otherwise crash the whole process rather than just this one key's work.
+     * A caller that cares about its own errors should catch and log inside `callback` itself.
+     */
+    schedule(key: string, callback: () => unknown): void;
+    /** Cancels `key`'s pending fire, if any. Idempotent -- an unknown or already-fired key is a safe no-op. */
+    cancel(key: string): void;
+    /** True while `key` has a fire pending. */
+    has(key: string): boolean;
+    /** Cancels every pending key at once -- for clean shutdown. */
+    clear(): void;
+}

package/dist/concurrency/debounced-scheduler.js

@@ -0,0 +1,92 @@
+/**
+ * Coalesces a burst of calls for the same key into exactly one callback fire,
+ * delayMs after the last call for that key -- the classic debounce shape,
+ * useful anywhere a flurry of raw upstream events for one logical unit of
+ * work (a filesystem save that fires more than once via temp-file write +
+ * atomic rename, a burst of webhook deliveries for the same resource) needs
+ * to collapse into a single downstream action. Different keys are fully
+ * independent. Pure timer bookkeeping, no I/O -- the callback itself does
+ * whatever real work is needed.
+ */
+export class DebounceCapacityExceeded extends Error {
+    key;
+    max;
+    constructor(key, max) {
+        super(`debounced scheduler distinct-key bound exceeded (${max}) scheduling key "${key}"`);
+        this.key = key;
+        this.max = max;
+        this.name = "DebounceCapacityExceeded";
+    }
+}
+const DEFAULT_MAX_KEYS = 4096;
+const NOOP_LOGGER = { debug() { }, warn() { } };
+export class DebouncedScheduler {
+    timers = new Map();
+    delayMs;
+    maxKeys;
+    logger;
+    constructor(delayMs, options = {}) {
+        if (!Number.isSafeInteger(delayMs) || delayMs < 0)
+            throw new TypeError("delayMs must be a non-negative safe integer");
+        this.delayMs = delayMs;
+        this.maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;
+        this.logger = options.logger ?? NOOP_LOGGER;
+    }
+    /**
+     * Schedules `callback` to run delayMs after this call, resetting any pending fire already
+     * scheduled for `key`. A callback that throws or rejects is caught and dropped -- there is
+     * no request awaiting this fire to report the error, and an unhandled timer failure would
+     * otherwise crash the whole process rather than just this one key's work.
+     * A caller that cares about its own errors should catch and log inside `callback` itself.
+     */
+    schedule(key, callback) {
+        const existing = this.timers.get(key);
+        if (existing) {
+            clearTimeout(existing);
+            this.logger.debug("debounced schedule coalesced", { component: "debounced-scheduler", operation: "schedule" });
+        }
+        else if (this.timers.size >= this.maxKeys) {
+            this.logger.warn("debounced schedule rejected", {
+                component: "debounced-scheduler",
+                operation: "schedule",
+                code: "DebounceCapacityExceeded",
+            });
+            throw new DebounceCapacityExceeded(key, this.maxKeys);
+        }
+        const reportFailure = (error) => {
+            this.logger.warn("debounced callback failed", {
+                component: "debounced-scheduler",
+                operation: "fire",
+                code: error instanceof Error ? error.name || "Error" : "Error",
+            });
+        };
+        const timer = setTimeout(() => {
+            this.timers.delete(key);
+            try {
+                Promise.resolve(callback()).catch(reportFailure);
+            }
+            catch (error) {
+                reportFailure(error);
+            }
+        }, this.delayMs);
+        this.timers.set(key, timer);
+    }
+    /** Cancels `key`'s pending fire, if any. Idempotent -- an unknown or already-fired key is a safe no-op. */
+    cancel(key) {
+        const existing = this.timers.get(key);
+        if (!existing)
+            return;
+        clearTimeout(existing);
+        this.timers.delete(key);
+    }
+    /** True while `key` has a fire pending. */
+    has(key) {
+        return this.timers.has(key);
+    }
+    /** Cancels every pending key at once -- for clean shutdown. */
+    clear() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+    }
+}

package/dist/concurrency/index.d.ts

@@ -0,0 +1 @@
+export * from "./debounced-scheduler.js";

package/dist/concurrency/index.js

@@ -0,0 +1 @@
+export * from "./debounced-scheduler.js";

package/dist/index.d.ts

@@ -5,14 +5,16 @@
  * (model-facing narrative blocks), operations (descriptors, effect
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
- * (Vehicle Jobs' pure pieces), schedules, watches, and persistence (atomic
- * JSON -- a technical utility, not a Vehicle protocol capability, kept
- * distinct for that reason). Every symbol below is re-exported unchanged
+ * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
+ * JSON), and concurrency (timer-based scheduling primitives) -- the latter
+ * two are technical utilities, not Vehicle protocol capabilities, kept
+ * distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
 export * from "./client/index.js";
+export * from "./concurrency/index.js";
 export * from "./content/index.js";
 export * from "./errors/index.js";
 export * from "./events/index.js";

package/dist/index.js

@@ -5,14 +5,16 @@
  * (model-facing narrative blocks), operations (descriptors, effect
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
- * (Vehicle Jobs' pure pieces), schedules, watches, and persistence (atomic
- * JSON -- a technical utility, not a Vehicle protocol capability, kept
- * distinct for that reason). Every symbol below is re-exported unchanged
+ * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
+ * JSON), and concurrency (timer-based scheduling primitives) -- the latter
+ * two are technical utilities, not Vehicle protocol capabilities, kept
+ * distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
 export * from "./client/index.js";
+export * from "./concurrency/index.js";
 export * from "./content/index.js";
 export * from "./errors/index.js";
 export * from "./events/index.js";

package/dist/schemas/index.d.ts

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/dist/schemas/index.js

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/dist/schemas/primitives.d.ts

@@ -0,0 +1,37 @@
+import type { VehicleSchemaIssue } from "./codec.js";
+/** The `{ success: false, issues }` half of VehicleSchemaResult -- named on its own since every hand-written safeParse's failure branch is this exact shape, never a bare Error. */
+export interface VehicleSchemaFailure {
+    readonly success: false;
+    readonly issues: readonly VehicleSchemaIssue[];
+}
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export declare function notAnObjectIssue(): VehicleSchemaFailure;
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export declare function schemaIssue(path: string | number | readonly (string | number)[], message: string): VehicleSchemaFailure;
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export declare function isSafeInteger(value: unknown): value is number;
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export declare function isPositiveSafeInteger(value: unknown, maximum?: number): value is number;
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export declare function isStringArray(value: unknown): value is string[];

package/dist/schemas/primitives.js

@@ -0,0 +1,47 @@
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export function notAnObjectIssue() {
+    return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+}
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export function schemaIssue(path, message) {
+    return { success: false, issues: [{ path: Array.isArray(path) ? path : [path], message }] };
+}
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export function isSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value);
+}
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export function isNonNegativeSafeInteger(value) {
+    return isSafeInteger(value) && value >= 0;
+}
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export function isPositiveSafeInteger(value, maximum) {
+    return isSafeInteger(value) && value >= 1 && (maximum === undefined || value <= maximum);
+}
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.18.0",
+	"version": "0.18.2",
 	"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/concurrency/debounced-scheduler.ts

@@ -0,0 +1,106 @@
+/**
+ * Coalesces a burst of calls for the same key into exactly one callback fire,
+ * delayMs after the last call for that key -- the classic debounce shape,
+ * useful anywhere a flurry of raw upstream events for one logical unit of
+ * work (a filesystem save that fires more than once via temp-file write +
+ * atomic rename, a burst of webhook deliveries for the same resource) needs
+ * to collapse into a single downstream action. Different keys are fully
+ * independent. Pure timer bookkeeping, no I/O -- the callback itself does
+ * whatever real work is needed.
+ */
+
+/** The minimal logging surface this module needs -- any real Logger (e.g. Vehicle's own daemon Logger) satisfies this structurally, no adapter required. */
+export interface MinimalLogger {
+	debug(msg: string, fields?: Record<string, unknown>): void;
+	warn(msg: string, fields?: Record<string, unknown>): void;
+}
+
+export class DebounceCapacityExceeded extends Error {
+	constructor(
+		readonly key: string,
+		readonly max: number,
+	) {
+		super(`debounced scheduler distinct-key bound exceeded (${max}) scheduling key "${key}"`);
+		this.name = "DebounceCapacityExceeded";
+	}
+}
+
+export interface DebouncedSchedulerOptions {
+	/** Maximum distinct keys with a pending fire at once. Default 4096. */
+	readonly maxKeys?: number;
+	readonly logger?: MinimalLogger;
+}
+
+const DEFAULT_MAX_KEYS = 4096;
+const NOOP_LOGGER: MinimalLogger = { debug() {}, warn() {} };
+
+export class DebouncedScheduler {
+	private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+	private readonly delayMs: number;
+	private readonly maxKeys: number;
+	private readonly logger: MinimalLogger;
+
+	constructor(delayMs: number, options: DebouncedSchedulerOptions = {}) {
+		if (!Number.isSafeInteger(delayMs) || delayMs < 0) throw new TypeError("delayMs must be a non-negative safe integer");
+		this.delayMs = delayMs;
+		this.maxKeys = options.maxKeys ?? DEFAULT_MAX_KEYS;
+		this.logger = options.logger ?? NOOP_LOGGER;
+	}
+
+	/**
+	 * Schedules `callback` to run delayMs after this call, resetting any pending fire already
+	 * scheduled for `key`. A callback that throws or rejects is caught and dropped -- there is
+	 * no request awaiting this fire to report the error, and an unhandled timer failure would
+	 * otherwise crash the whole process rather than just this one key's work.
+	 * A caller that cares about its own errors should catch and log inside `callback` itself.
+	 */
+	schedule(key: string, callback: () => unknown): void {
+		const existing = this.timers.get(key);
+		if (existing) {
+			clearTimeout(existing);
+			this.logger.debug("debounced schedule coalesced", { component: "debounced-scheduler", operation: "schedule" });
+		} else if (this.timers.size >= this.maxKeys) {
+			this.logger.warn("debounced schedule rejected", {
+				component: "debounced-scheduler",
+				operation: "schedule",
+				code: "DebounceCapacityExceeded",
+			});
+			throw new DebounceCapacityExceeded(key, this.maxKeys);
+		}
+		const reportFailure = (error: unknown): void => {
+			this.logger.warn("debounced callback failed", {
+				component: "debounced-scheduler",
+				operation: "fire",
+				code: error instanceof Error ? error.name || "Error" : "Error",
+			});
+		};
+		const timer = setTimeout(() => {
+			this.timers.delete(key);
+			try {
+				Promise.resolve(callback()).catch(reportFailure);
+			} catch (error: unknown) {
+				reportFailure(error);
+			}
+		}, this.delayMs);
+		this.timers.set(key, timer);
+	}
+
+	/** Cancels `key`'s pending fire, if any. Idempotent -- an unknown or already-fired key is a safe no-op. */
+	cancel(key: string): void {
+		const existing = this.timers.get(key);
+		if (!existing) return;
+		clearTimeout(existing);
+		this.timers.delete(key);
+	}
+
+	/** True while `key` has a fire pending. */
+	has(key: string): boolean {
+		return this.timers.has(key);
+	}
+
+	/** Cancels every pending key at once -- for clean shutdown. */
+	clear(): void {
+		for (const timer of this.timers.values()) clearTimeout(timer);
+		this.timers.clear();
+	}
+}

package/src/concurrency/index.ts

@@ -0,0 +1 @@
+export * from "./debounced-scheduler.js";

package/src/index.ts

@@ -5,14 +5,16 @@
  * (model-facing narrative blocks), operations (descriptors, effect
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
- * (Vehicle Jobs' pure pieces), schedules, watches, and persistence (atomic
- * JSON -- a technical utility, not a Vehicle protocol capability, kept
- * distinct for that reason). Every symbol below is re-exported unchanged
+ * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
+ * JSON), and concurrency (timer-based scheduling primitives) -- the latter
+ * two are technical utilities, not Vehicle protocol capabilities, kept
+ * distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
 export * from "./client/index.js";
+export * from "./concurrency/index.js";
 export * from "./content/index.js";
 export * from "./errors/index.js";
 export * from "./events/index.js";

package/src/schemas/index.ts

@@ -2,3 +2,4 @@ export * from "./codec.js";
 export * from "./json.js";
 export * from "./loose-object.js";
 export * from "./presentation.js";
+export * from "./primitives.js";

package/src/schemas/primitives.ts

@@ -0,0 +1,62 @@
+import type { VehicleSchemaIssue } from "./codec.js";
+
+/** The `{ success: false, issues }` half of VehicleSchemaResult -- named on its own since every hand-written safeParse's failure branch is this exact shape, never a bare Error. */
+export interface VehicleSchemaFailure {
+	readonly success: false;
+	readonly issues: readonly VehicleSchemaIssue[];
+}
+
+/**
+ * A safeParse's own first, universal check: the value wasn't even an object. Every hand-written
+ * object-shaped VehicleSchemaCodec across the ecosystem re-derived this exact literal before this
+ * existed as a shared primitive -- one canonical wording now, not five near-identical copies.
+ */
+export function notAnObjectIssue(): VehicleSchemaFailure {
+	return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+}
+
+/**
+ * One field-scoped failure. `path` accepts a single key (the common case: a top-level field) or
+ * a full path segment array (for a nested/array-indexed field, matching VehicleSchemaIssue.path's
+ * own `readonly (string | number)[]` shape directly) -- both real shapes existing hand-written
+ * safeParse implementations across the ecosystem already needed.
+ */
+export function schemaIssue(path: string | number | readonly (string | number)[], message: string): VehicleSchemaFailure {
+	return { success: false, issues: [{ path: Array.isArray(path) ? path : [path], message }] };
+}
+
+/** True for a real object value -- not null, not an array (JSON Schema's own object/array distinction; `typeof [] === "object"` is not what a caller checking "is this a plain object" means). */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A non-empty string -- the shape every identifier-like field (workspaceId, ref, path, ...) across the ecosystem actually requires; an empty string is a real, distinct failure from "not a string at all". */
+export function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/** A real integer safely representable in a double -- the base every bounded-count/size field below builds on. */
+export function isSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value);
+}
+
+/** A safe integer that is zero or more -- e.g. an offset/cursor field where zero is a real, valid value, unlike a positive-only count. */
+export function isNonNegativeSafeInteger(value: unknown): value is number {
+	return isSafeInteger(value) && value >= 0;
+}
+
+/**
+ * A safe integer that is at least 1 -- the shape every bounded-count/size field (maxBytes,
+ * maxCount, maxResults, maxMatches, ...) across the ecosystem actually requires. `maximum`, when
+ * given, additionally caps the accepted value inclusively -- a field that must be positive AND
+ * never exceed some hard ceiling (e.g. a page size capped well below an unbounded read) is a real,
+ * recurring combination, not a hypothetical one.
+ */
+export function isPositiveSafeInteger(value: unknown, maximum?: number): value is number {
+	return isSafeInteger(value) && value >= 1 && (maximum === undefined || value <= maximum);
+}
+
+/** An array whose every element is a string -- the shape every string-list field (labels, tags, pathspecs, ...) across the ecosystem actually requires; a mixed-type array is a real, distinct failure from "not an array at all". */
+export function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}