@streetui/scheduler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreetUI 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/README.md

@@ -0,0 +1,26 @@
+# @streetui/scheduler
+
+StreetUI update scheduler — batching, microtask flushing, ordered queues
+
+Part of [StreetUI](https://github.com/streetui/streetui) — a semantic,
+signal-based UI framework with its own reactivity and keyed DOM reconciler
+(no virtual DOM).
+
+## Install
+
+```sh
+npm install @streetui/scheduler
+```
+
+## Usage
+
+```ts
+import * as pkg from '@streetui/scheduler';
+```
+
+Both ESM (`import`) and CommonJS (`require`) entry points are shipped, with
+matching TypeScript declarations.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Scheduler: () => Scheduler,
+  flushSync: () => flushSync,
+  scheduleImmediate: () => scheduleImmediate,
+  scheduleUpdate: () => scheduleUpdate,
+  scheduler: () => scheduler
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/scheduler.ts
+var PRIORITY_ORDER = {
+  immediate: 0,
+  normal: 1,
+  idle: 2
+};
+var Scheduler = class {
+  _queue = /* @__PURE__ */ new Map();
+  _flushScheduled = false;
+  _flushing = false;
+  _diagnostics = void 0;
+  /**
+   * Install an optional diagnostic sink for swallowed job errors. Pass
+   * `undefined` to restore the default `console.error` reporting. Additive and
+   * opt-in — the scheduler never sends anything anywhere on its own.
+   */
+  setDiagnostics(sink) {
+    this._diagnostics = sink;
+  }
+  /** Total jobs currently queued. */
+  get size() {
+    return this._queue.size;
+  }
+  /** True if a flush has been scheduled but not yet executed. */
+  get isPending() {
+    return this._flushScheduled;
+  }
+  /**
+   * Enqueue a job. If a job with the same key exists, the new one replaces it
+   * (allowing callers to coalesce repeated updates for the same node).
+   */
+  schedule(job) {
+    this._queue.set(job.key, job);
+    if (!this._flushScheduled && !this._flushing) {
+      this._flushScheduled = true;
+      this._scheduleMicrotask();
+    }
+  }
+  /** Schedule multiple jobs atomically. */
+  scheduleAll(jobs) {
+    for (const job of jobs) {
+      this._queue.set(job.key, job);
+    }
+    if (!this._flushScheduled && !this._flushing && this._queue.size > 0) {
+      this._flushScheduled = true;
+      this._scheduleMicrotask();
+    }
+  }
+  /**
+   * Cancel a queued job by key. No-op if not queued.
+   */
+  cancel(key) {
+    this._queue.delete(key);
+  }
+  /**
+   * Synchronously flush all queued jobs (sorted by priority).
+   * Useful in tests and for immediate rendering.
+   */
+  flush() {
+    if (this._flushing) return;
+    this._flushScheduled = false;
+    this._flushing = true;
+    const jobs = Array.from(this._queue.values()).sort(
+      (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]
+    );
+    this._queue.clear();
+    try {
+      for (const job of jobs) {
+        try {
+          job.fn();
+        } catch (err) {
+          if (this._diagnostics?.error) {
+            this._diagnostics.error(`Scheduler job "${job.key}" threw`, err);
+          } else {
+            console.error(`[Scheduler] Job "${job.key}" threw:`, err);
+          }
+        }
+      }
+    } finally {
+      this._flushing = false;
+    }
+  }
+  /** Clear all pending jobs without executing them. */
+  clear() {
+    this._queue.clear();
+    this._flushScheduled = false;
+  }
+  _scheduleMicrotask() {
+    Promise.resolve().then(() => {
+      if (this._flushScheduled) {
+        this.flush();
+      }
+    });
+  }
+};
+var scheduler = new Scheduler();
+function scheduleUpdate(key, fn) {
+  scheduler.schedule({ key, priority: "normal", fn });
+}
+function scheduleImmediate(key, fn) {
+  scheduler.schedule({ key, priority: "immediate", fn });
+}
+function flushSync() {
+  scheduler.flush();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Scheduler,
+  flushSync,
+  scheduleImmediate,
+  scheduleUpdate,
+  scheduler
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/scheduler.ts"],"sourcesContent":["export * from './scheduler.js';\n","/**\n * StreetUI update scheduler.\n *\n * Responsibilities:\n *  - Queue update callbacks\n *  - Batch synchronous enqueues into a single microtask flush\n *  - Guarantee ordering: higher priority jobs flush first\n *  - Prevent duplicate work for the same job key\n *  - Allow synchronous flush for tests\n */\n\nexport type Priority = 'immediate' | 'normal' | 'idle';\n\nconst PRIORITY_ORDER: Record<Priority, number> = {\n  immediate: 0,\n  normal: 1,\n  idle: 2,\n};\n\nexport interface Job {\n  /** Unique key — if another job with the same key is already queued, it is replaced. */\n  readonly key: string;\n  readonly priority: Priority;\n  readonly fn: () => void;\n}\n\n/**\n * Optional error-reporting hook (v0.9 §26/§27). Structurally compatible with\n * `@streetui/core`'s `DiagnosticSink` (the `error` method) so an application can\n * route swallowed scheduler-job failures through its own logger instead of the\n * default `console.error`. Kept as a local structural type so the scheduler\n * stays dependency-free; no network, no telemetry. When unset, behaviour is\n * exactly as before.\n */\nexport interface SchedulerDiagnostics {\n  error?(message: string, context?: unknown): void;\n}\n\nexport class Scheduler {\n  private readonly _queue: Map<string, Job> = new Map();\n  private _flushScheduled = false;\n  private _flushing = false;\n  private _diagnostics: SchedulerDiagnostics | undefined = undefined;\n\n  /**\n   * Install an optional diagnostic sink for swallowed job errors. Pass\n   * `undefined` to restore the default `console.error` reporting. Additive and\n   * opt-in — the scheduler never sends anything anywhere on its own.\n   */\n  setDiagnostics(sink: SchedulerDiagnostics | undefined): void {\n    this._diagnostics = sink;\n  }\n\n  /** Total jobs currently queued. */\n  get size(): number {\n    return this._queue.size;\n  }\n\n  /** True if a flush has been scheduled but not yet executed. */\n  get isPending(): boolean {\n    return this._flushScheduled;\n  }\n\n  /**\n   * Enqueue a job. If a job with the same key exists, the new one replaces it\n   * (allowing callers to coalesce repeated updates for the same node).\n   */\n  schedule(job: Job): void {\n    this._queue.set(job.key, job);\n    if (!this._flushScheduled && !this._flushing) {\n      this._flushScheduled = true;\n      this._scheduleMicrotask();\n    }\n  }\n\n  /** Schedule multiple jobs atomically. */\n  scheduleAll(jobs: readonly Job[]): void {\n    for (const job of jobs) {\n      this._queue.set(job.key, job);\n    }\n    if (!this._flushScheduled && !this._flushing && this._queue.size > 0) {\n      this._flushScheduled = true;\n      this._scheduleMicrotask();\n    }\n  }\n\n  /**\n   * Cancel a queued job by key. No-op if not queued.\n   */\n  cancel(key: string): void {\n    this._queue.delete(key);\n  }\n\n  /**\n   * Synchronously flush all queued jobs (sorted by priority).\n   * Useful in tests and for immediate rendering.\n   */\n  flush(): void {\n    if (this._flushing) return;\n    this._flushScheduled = false;\n    this._flushing = true;\n\n    const jobs = Array.from(this._queue.values()).sort(\n      (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority],\n    );\n    this._queue.clear();\n\n    try {\n      for (const job of jobs) {\n        try {\n          job.fn();\n        } catch (err) {\n          // Isolate job failures — report and continue so remaining jobs still run.\n          if (this._diagnostics?.error) {\n            this._diagnostics.error(`Scheduler job \"${job.key}\" threw`, err);\n          } else {\n            console.error(`[Scheduler] Job \"${job.key}\" threw:`, err);\n          }\n        }\n      }\n    } finally {\n      this._flushing = false;\n    }\n  }\n\n  /** Clear all pending jobs without executing them. */\n  clear(): void {\n    this._queue.clear();\n    this._flushScheduled = false;\n  }\n\n  private _scheduleMicrotask(): void {\n    Promise.resolve().then(() => {\n      if (this._flushScheduled) {\n        this.flush();\n      }\n    });\n  }\n}\n\n/** The shared global scheduler instance. */\nexport const scheduler = new Scheduler();\n\n/** Convenience: schedule a normal-priority job. */\nexport function scheduleUpdate(key: string, fn: () => void): void {\n  scheduler.schedule({ key, priority: 'normal', fn });\n}\n\n/** Convenience: schedule an immediate-priority job. */\nexport function scheduleImmediate(key: string, fn: () => void): void {\n  scheduler.schedule({ key, priority: 'immediate', fn });\n}\n\n/** Convenience: flush the global scheduler synchronously. */\nexport function flushSync(): void {\n  scheduler.flush();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACaA,IAAM,iBAA2C;AAAA,EAC/C,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,MAAM;AACR;AAqBO,IAAM,YAAN,MAAgB;AAAA,EACJ,SAA2B,oBAAI,IAAI;AAAA,EAC5C,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,eAAiD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOzD,eAAe,MAA8C;AAC3D,SAAK,eAAe;AAAA,EACtB;AAAA;AAAA,EAGA,IAAI,OAAe;AACjB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA,EAGA,IAAI,YAAqB;AACvB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAS,KAAgB;AACvB,SAAK,OAAO,IAAI,IAAI,KAAK,GAAG;AAC5B,QAAI,CAAC,KAAK,mBAAmB,CAAC,KAAK,WAAW;AAC5C,WAAK,kBAAkB;AACvB,WAAK,mBAAmB;AAAA,IAC1B;AAAA,EACF;AAAA;AAAA,EAGA,YAAY,MAA4B;AACtC,eAAW,OAAO,MAAM;AACtB,WAAK,OAAO,IAAI,IAAI,KAAK,GAAG;AAAA,IAC9B;AACA,QAAI,CAAC,KAAK,mBAAmB,CAAC,KAAK,aAAa,KAAK,OAAO,OAAO,GAAG;AACpE,WAAK,kBAAkB;AACvB,WAAK,mBAAmB;AAAA,IAC1B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,KAAmB;AACxB,SAAK,OAAO,OAAO,GAAG;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAc;AACZ,QAAI,KAAK,UAAW;AACpB,SAAK,kBAAkB;AACvB,SAAK,YAAY;AAEjB,UAAM,OAAO,MAAM,KAAK,KAAK,OAAO,OAAO,CAAC,EAAE;AAAA,MAC5C,CAAC,GAAG,MAAM,eAAe,EAAE,QAAQ,IAAI,eAAe,EAAE,QAAQ;AAAA,IAClE;AACA,SAAK,OAAO,MAAM;AAElB,QAAI;AACF,iBAAW,OAAO,MAAM;AACtB,YAAI;AACF,cAAI,GAAG;AAAA,QACT,SAAS,KAAK;AAEZ,cAAI,KAAK,cAAc,OAAO;AAC5B,iBAAK,aAAa,MAAM,kBAAkB,IAAI,GAAG,WAAW,GAAG;AAAA,UACjE,OAAO;AACL,oBAAQ,MAAM,oBAAoB,IAAI,GAAG,YAAY,GAAG;AAAA,UAC1D;AAAA,QACF;AAAA,MACF;AAAA,IACF,UAAE;AACA,WAAK,YAAY;AAAA,IACnB;AAAA,EACF;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,OAAO,MAAM;AAClB,SAAK,kBAAkB;AAAA,EACzB;AAAA,EAEQ,qBAA2B;AACjC,YAAQ,QAAQ,EAAE,KAAK,MAAM;AAC3B,UAAI,KAAK,iBAAiB;AACxB,aAAK,MAAM;AAAA,MACb;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAGO,IAAM,YAAY,IAAI,UAAU;AAGhC,SAAS,eAAe,KAAa,IAAsB;AAChE,YAAU,SAAS,EAAE,KAAK,UAAU,UAAU,GAAG,CAAC;AACpD;AAGO,SAAS,kBAAkB,KAAa,IAAsB;AACnE,YAAU,SAAS,EAAE,KAAK,UAAU,aAAa,GAAG,CAAC;AACvD;AAGO,SAAS,YAAkB;AAChC,YAAU,MAAM;AAClB;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+/**
+ * StreetUI update scheduler.
+ *
+ * Responsibilities:
+ *  - Queue update callbacks
+ *  - Batch synchronous enqueues into a single microtask flush
+ *  - Guarantee ordering: higher priority jobs flush first
+ *  - Prevent duplicate work for the same job key
+ *  - Allow synchronous flush for tests
+ */
+type Priority = 'immediate' | 'normal' | 'idle';
+interface Job {
+    /** Unique key — if another job with the same key is already queued, it is replaced. */
+    readonly key: string;
+    readonly priority: Priority;
+    readonly fn: () => void;
+}
+/**
+ * Optional error-reporting hook (v0.9 §26/§27). Structurally compatible with
+ * `@streetui/core`'s `DiagnosticSink` (the `error` method) so an application can
+ * route swallowed scheduler-job failures through its own logger instead of the
+ * default `console.error`. Kept as a local structural type so the scheduler
+ * stays dependency-free; no network, no telemetry. When unset, behaviour is
+ * exactly as before.
+ */
+interface SchedulerDiagnostics {
+    error?(message: string, context?: unknown): void;
+}
+declare class Scheduler {
+    private readonly _queue;
+    private _flushScheduled;
+    private _flushing;
+    private _diagnostics;
+    /**
+     * Install an optional diagnostic sink for swallowed job errors. Pass
+     * `undefined` to restore the default `console.error` reporting. Additive and
+     * opt-in — the scheduler never sends anything anywhere on its own.
+     */
+    setDiagnostics(sink: SchedulerDiagnostics | undefined): void;
+    /** Total jobs currently queued. */
+    get size(): number;
+    /** True if a flush has been scheduled but not yet executed. */
+    get isPending(): boolean;
+    /**
+     * Enqueue a job. If a job with the same key exists, the new one replaces it
+     * (allowing callers to coalesce repeated updates for the same node).
+     */
+    schedule(job: Job): void;
+    /** Schedule multiple jobs atomically. */
+    scheduleAll(jobs: readonly Job[]): void;
+    /**
+     * Cancel a queued job by key. No-op if not queued.
+     */
+    cancel(key: string): void;
+    /**
+     * Synchronously flush all queued jobs (sorted by priority).
+     * Useful in tests and for immediate rendering.
+     */
+    flush(): void;
+    /** Clear all pending jobs without executing them. */
+    clear(): void;
+    private _scheduleMicrotask;
+}
+/** The shared global scheduler instance. */
+declare const scheduler: Scheduler;
+/** Convenience: schedule a normal-priority job. */
+declare function scheduleUpdate(key: string, fn: () => void): void;
+/** Convenience: schedule an immediate-priority job. */
+declare function scheduleImmediate(key: string, fn: () => void): void;
+/** Convenience: flush the global scheduler synchronously. */
+declare function flushSync(): void;
+
+export { type Job, type Priority, Scheduler, type SchedulerDiagnostics, flushSync, scheduleImmediate, scheduleUpdate, scheduler };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * StreetUI update scheduler.
+ *
+ * Responsibilities:
+ *  - Queue update callbacks
+ *  - Batch synchronous enqueues into a single microtask flush
+ *  - Guarantee ordering: higher priority jobs flush first
+ *  - Prevent duplicate work for the same job key
+ *  - Allow synchronous flush for tests
+ */
+type Priority = 'immediate' | 'normal' | 'idle';
+interface Job {
+    /** Unique key — if another job with the same key is already queued, it is replaced. */
+    readonly key: string;
+    readonly priority: Priority;
+    readonly fn: () => void;
+}
+/**
+ * Optional error-reporting hook (v0.9 §26/§27). Structurally compatible with
+ * `@streetui/core`'s `DiagnosticSink` (the `error` method) so an application can
+ * route swallowed scheduler-job failures through its own logger instead of the
+ * default `console.error`. Kept as a local structural type so the scheduler
+ * stays dependency-free; no network, no telemetry. When unset, behaviour is
+ * exactly as before.
+ */
+interface SchedulerDiagnostics {
+    error?(message: string, context?: unknown): void;
+}
+declare class Scheduler {
+    private readonly _queue;
+    private _flushScheduled;
+    private _flushing;
+    private _diagnostics;
+    /**
+     * Install an optional diagnostic sink for swallowed job errors. Pass
+     * `undefined` to restore the default `console.error` reporting. Additive and
+     * opt-in — the scheduler never sends anything anywhere on its own.
+     */
+    setDiagnostics(sink: SchedulerDiagnostics | undefined): void;
+    /** Total jobs currently queued. */
+    get size(): number;
+    /** True if a flush has been scheduled but not yet executed. */
+    get isPending(): boolean;
+    /**
+     * Enqueue a job. If a job with the same key exists, the new one replaces it
+     * (allowing callers to coalesce repeated updates for the same node).
+     */
+    schedule(job: Job): void;
+    /** Schedule multiple jobs atomically. */
+    scheduleAll(jobs: readonly Job[]): void;
+    /**
+     * Cancel a queued job by key. No-op if not queued.
+     */
+    cancel(key: string): void;
+    /**
+     * Synchronously flush all queued jobs (sorted by priority).
+     * Useful in tests and for immediate rendering.
+     */
+    flush(): void;
+    /** Clear all pending jobs without executing them. */
+    clear(): void;
+    private _scheduleMicrotask;
+}
+/** The shared global scheduler instance. */
+declare const scheduler: Scheduler;
+/** Convenience: schedule a normal-priority job. */
+declare function scheduleUpdate(key: string, fn: () => void): void;
+/** Convenience: schedule an immediate-priority job. */
+declare function scheduleImmediate(key: string, fn: () => void): void;
+/** Convenience: flush the global scheduler synchronously. */
+declare function flushSync(): void;
+
+export { type Job, type Priority, Scheduler, type SchedulerDiagnostics, flushSync, scheduleImmediate, scheduleUpdate, scheduler };

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/scheduler.ts
+var PRIORITY_ORDER = {
+  immediate: 0,
+  normal: 1,
+  idle: 2
+};
+var Scheduler = class {
+  _queue = /* @__PURE__ */ new Map();
+  _flushScheduled = false;
+  _flushing = false;
+  _diagnostics = void 0;
+  /**
+   * Install an optional diagnostic sink for swallowed job errors. Pass
+   * `undefined` to restore the default `console.error` reporting. Additive and
+   * opt-in — the scheduler never sends anything anywhere on its own.
+   */
+  setDiagnostics(sink) {
+    this._diagnostics = sink;
+  }
+  /** Total jobs currently queued. */
+  get size() {
+    return this._queue.size;
+  }
+  /** True if a flush has been scheduled but not yet executed. */
+  get isPending() {
+    return this._flushScheduled;
+  }
+  /**
+   * Enqueue a job. If a job with the same key exists, the new one replaces it
+   * (allowing callers to coalesce repeated updates for the same node).
+   */
+  schedule(job) {
+    this._queue.set(job.key, job);
+    if (!this._flushScheduled && !this._flushing) {
+      this._flushScheduled = true;
+      this._scheduleMicrotask();
+    }
+  }
+  /** Schedule multiple jobs atomically. */
+  scheduleAll(jobs) {
+    for (const job of jobs) {
+      this._queue.set(job.key, job);
+    }
+    if (!this._flushScheduled && !this._flushing && this._queue.size > 0) {
+      this._flushScheduled = true;
+      this._scheduleMicrotask();
+    }
+  }
+  /**
+   * Cancel a queued job by key. No-op if not queued.
+   */
+  cancel(key) {
+    this._queue.delete(key);
+  }
+  /**
+   * Synchronously flush all queued jobs (sorted by priority).
+   * Useful in tests and for immediate rendering.
+   */
+  flush() {
+    if (this._flushing) return;
+    this._flushScheduled = false;
+    this._flushing = true;
+    const jobs = Array.from(this._queue.values()).sort(
+      (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]
+    );
+    this._queue.clear();
+    try {
+      for (const job of jobs) {
+        try {
+          job.fn();
+        } catch (err) {
+          if (this._diagnostics?.error) {
+            this._diagnostics.error(`Scheduler job "${job.key}" threw`, err);
+          } else {
+            console.error(`[Scheduler] Job "${job.key}" threw:`, err);
+          }
+        }
+      }
+    } finally {
+      this._flushing = false;
+    }
+  }
+  /** Clear all pending jobs without executing them. */
+  clear() {
+    this._queue.clear();
+    this._flushScheduled = false;
+  }
+  _scheduleMicrotask() {
+    Promise.resolve().then(() => {
+      if (this._flushScheduled) {
+        this.flush();
+      }
+    });
+  }
+};
+var scheduler = new Scheduler();
+function scheduleUpdate(key, fn) {
+  scheduler.schedule({ key, priority: "normal", fn });
+}
+function scheduleImmediate(key, fn) {
+  scheduler.schedule({ key, priority: "immediate", fn });
+}
+function flushSync() {
+  scheduler.flush();
+}
+export {
+  Scheduler,
+  flushSync,
+  scheduleImmediate,
+  scheduleUpdate,
+  scheduler
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scheduler.ts"],"sourcesContent":["/**\n * StreetUI update scheduler.\n *\n * Responsibilities:\n *  - Queue update callbacks\n *  - Batch synchronous enqueues into a single microtask flush\n *  - Guarantee ordering: higher priority jobs flush first\n *  - Prevent duplicate work for the same job key\n *  - Allow synchronous flush for tests\n */\n\nexport type Priority = 'immediate' | 'normal' | 'idle';\n\nconst PRIORITY_ORDER: Record<Priority, number> = {\n  immediate: 0,\n  normal: 1,\n  idle: 2,\n};\n\nexport interface Job {\n  /** Unique key — if another job with the same key is already queued, it is replaced. */\n  readonly key: string;\n  readonly priority: Priority;\n  readonly fn: () => void;\n}\n\n/**\n * Optional error-reporting hook (v0.9 §26/§27). Structurally compatible with\n * `@streetui/core`'s `DiagnosticSink` (the `error` method) so an application can\n * route swallowed scheduler-job failures through its own logger instead of the\n * default `console.error`. Kept as a local structural type so the scheduler\n * stays dependency-free; no network, no telemetry. When unset, behaviour is\n * exactly as before.\n */\nexport interface SchedulerDiagnostics {\n  error?(message: string, context?: unknown): void;\n}\n\nexport class Scheduler {\n  private readonly _queue: Map<string, Job> = new Map();\n  private _flushScheduled = false;\n  private _flushing = false;\n  private _diagnostics: SchedulerDiagnostics | undefined = undefined;\n\n  /**\n   * Install an optional diagnostic sink for swallowed job errors. Pass\n   * `undefined` to restore the default `console.error` reporting. Additive and\n   * opt-in — the scheduler never sends anything anywhere on its own.\n   */\n  setDiagnostics(sink: SchedulerDiagnostics | undefined): void {\n    this._diagnostics = sink;\n  }\n\n  /** Total jobs currently queued. */\n  get size(): number {\n    return this._queue.size;\n  }\n\n  /** True if a flush has been scheduled but not yet executed. */\n  get isPending(): boolean {\n    return this._flushScheduled;\n  }\n\n  /**\n   * Enqueue a job. If a job with the same key exists, the new one replaces it\n   * (allowing callers to coalesce repeated updates for the same node).\n   */\n  schedule(job: Job): void {\n    this._queue.set(job.key, job);\n    if (!this._flushScheduled && !this._flushing) {\n      this._flushScheduled = true;\n      this._scheduleMicrotask();\n    }\n  }\n\n  /** Schedule multiple jobs atomically. */\n  scheduleAll(jobs: readonly Job[]): void {\n    for (const job of jobs) {\n      this._queue.set(job.key, job);\n    }\n    if (!this._flushScheduled && !this._flushing && this._queue.size > 0) {\n      this._flushScheduled = true;\n      this._scheduleMicrotask();\n    }\n  }\n\n  /**\n   * Cancel a queued job by key. No-op if not queued.\n   */\n  cancel(key: string): void {\n    this._queue.delete(key);\n  }\n\n  /**\n   * Synchronously flush all queued jobs (sorted by priority).\n   * Useful in tests and for immediate rendering.\n   */\n  flush(): void {\n    if (this._flushing) return;\n    this._flushScheduled = false;\n    this._flushing = true;\n\n    const jobs = Array.from(this._queue.values()).sort(\n      (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority],\n    );\n    this._queue.clear();\n\n    try {\n      for (const job of jobs) {\n        try {\n          job.fn();\n        } catch (err) {\n          // Isolate job failures — report and continue so remaining jobs still run.\n          if (this._diagnostics?.error) {\n            this._diagnostics.error(`Scheduler job \"${job.key}\" threw`, err);\n          } else {\n            console.error(`[Scheduler] Job \"${job.key}\" threw:`, err);\n          }\n        }\n      }\n    } finally {\n      this._flushing = false;\n    }\n  }\n\n  /** Clear all pending jobs without executing them. */\n  clear(): void {\n    this._queue.clear();\n    this._flushScheduled = false;\n  }\n\n  private _scheduleMicrotask(): void {\n    Promise.resolve().then(() => {\n      if (this._flushScheduled) {\n        this.flush();\n      }\n    });\n  }\n}\n\n/** The shared global scheduler instance. */\nexport const scheduler = new Scheduler();\n\n/** Convenience: schedule a normal-priority job. */\nexport function scheduleUpdate(key: string, fn: () => void): void {\n  scheduler.schedule({ key, priority: 'normal', fn });\n}\n\n/** Convenience: schedule an immediate-priority job. */\nexport function scheduleImmediate(key: string, fn: () => void): void {\n  scheduler.schedule({ key, priority: 'immediate', fn });\n}\n\n/** Convenience: flush the global scheduler synchronously. */\nexport function flushSync(): void {\n  scheduler.flush();\n}\n"],"mappings":";AAaA,IAAM,iBAA2C;AAAA,EAC/C,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,MAAM;AACR;AAqBO,IAAM,YAAN,MAAgB;AAAA,EACJ,SAA2B,oBAAI,IAAI;AAAA,EAC5C,kBAAkB;AAAA,EAClB,YAAY;AAAA,EACZ,eAAiD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOzD,eAAe,MAA8C;AAC3D,SAAK,eAAe;AAAA,EACtB;AAAA;AAAA,EAGA,IAAI,OAAe;AACjB,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA,EAGA,IAAI,YAAqB;AACvB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAS,KAAgB;AACvB,SAAK,OAAO,IAAI,IAAI,KAAK,GAAG;AAC5B,QAAI,CAAC,KAAK,mBAAmB,CAAC,KAAK,WAAW;AAC5C,WAAK,kBAAkB;AACvB,WAAK,mBAAmB;AAAA,IAC1B;AAAA,EACF;AAAA;AAAA,EAGA,YAAY,MAA4B;AACtC,eAAW,OAAO,MAAM;AACtB,WAAK,OAAO,IAAI,IAAI,KAAK,GAAG;AAAA,IAC9B;AACA,QAAI,CAAC,KAAK,mBAAmB,CAAC,KAAK,aAAa,KAAK,OAAO,OAAO,GAAG;AACpE,WAAK,kBAAkB;AACvB,WAAK,mBAAmB;AAAA,IAC1B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,KAAmB;AACxB,SAAK,OAAO,OAAO,GAAG;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,QAAc;AACZ,QAAI,KAAK,UAAW;AACpB,SAAK,kBAAkB;AACvB,SAAK,YAAY;AAEjB,UAAM,OAAO,MAAM,KAAK,KAAK,OAAO,OAAO,CAAC,EAAE;AAAA,MAC5C,CAAC,GAAG,MAAM,eAAe,EAAE,QAAQ,IAAI,eAAe,EAAE,QAAQ;AAAA,IAClE;AACA,SAAK,OAAO,MAAM;AAElB,QAAI;AACF,iBAAW,OAAO,MAAM;AACtB,YAAI;AACF,cAAI,GAAG;AAAA,QACT,SAAS,KAAK;AAEZ,cAAI,KAAK,cAAc,OAAO;AAC5B,iBAAK,aAAa,MAAM,kBAAkB,IAAI,GAAG,WAAW,GAAG;AAAA,UACjE,OAAO;AACL,oBAAQ,MAAM,oBAAoB,IAAI,GAAG,YAAY,GAAG;AAAA,UAC1D;AAAA,QACF;AAAA,MACF;AAAA,IACF,UAAE;AACA,WAAK,YAAY;AAAA,IACnB;AAAA,EACF;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,OAAO,MAAM;AAClB,SAAK,kBAAkB;AAAA,EACzB;AAAA,EAEQ,qBAA2B;AACjC,YAAQ,QAAQ,EAAE,KAAK,MAAM;AAC3B,UAAI,KAAK,iBAAiB;AACxB,aAAK,MAAM;AAAA,MACb;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAGO,IAAM,YAAY,IAAI,UAAU;AAGhC,SAAS,eAAe,KAAa,IAAsB;AAChE,YAAU,SAAS,EAAE,KAAK,UAAU,UAAU,GAAG,CAAC;AACpD;AAGO,SAAS,kBAAkB,KAAa,IAAsB;AACnE,YAAU,SAAS,EAAE,KAAK,UAAU,aAAa,GAAG,CAAC;AACvD;AAGO,SAAS,YAAkB;AAChC,YAAU,MAAM;AAClB;","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@streetui/scheduler",
+  "version": "1.0.0",
+  "description": "StreetUI update scheduler — batching, microtask flushing, ordered queues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "*",
+    "tsup": "*",
+    "vitest": "*"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}