@provino/timers 0.0.0-stage → 0.1.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pixel Perfect Software
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ # @provino/timers
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The fake clock, over `@sinonjs/fake-timers`, and the timer members of a dialect's `jest` object built on it. A dialect's timers policy supplies every value. Legacy fake timers are not built.
4
+
5
+ This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner that is pre-alpha and not on npm yet. The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
6
+
7
+ **Versioning:** this package is `@beta` as a whole. There is no semver promise for it before 1.0, and its API can change in any release.
8
+
9
+ [MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
@@ -0,0 +1,177 @@
1
+ import { TimersPolicy } from "@provino/types";
2
+ /**
3
+ * A global the clock can replace: the names `@sinonjs/fake-timers` 15.4 takes.
4
+ * @public
5
+ */
6
+ type FakeMethod = "setTimeout" | "clearTimeout" | "setImmediate" | "clearImmediate" | "setInterval" | "clearInterval" | "Date" | "nextTick" | "hrtime" | "requestAnimationFrame" | "cancelAnimationFrame" | "requestIdleCallback" | "cancelIdleCallback" | "performance" | "queueMicrotask" | "Intl" | "Temporal";
7
+ /**
8
+ * A `Temporal.Instant` or `Temporal.ZonedDateTime`, as far as the clock reads one.
9
+ * @public
10
+ */
11
+ interface TemporalTimelike {
12
+ readonly epochMilliseconds: number;
13
+ }
14
+ /**
15
+ * A `Temporal.Duration`, as far as the clock reads one.
16
+ * @public
17
+ */
18
+ interface TemporalDurationLike {
19
+ total(options: {
20
+ unit: "millisecond";
21
+ }): number;
22
+ }
23
+ /**
24
+ * What `install` takes. A dialect's `optionNames` (`TimersPolicy`) picks which half is read: Jest's
25
+ * `fakeTimers` names (`doNotFake`, `advanceTimers`, `timerLimit`, `legacyFakeTimers`) or Vitest's
26
+ * (`toFake`, `toNotFake`, `shouldAdvanceTime`, `advanceTimeDelta`, `loopLimit`,
27
+ * `shouldClearNativeTimers`). The other half is ignored, as each runner ignores the other's names.
28
+ * `now` is read under both.
29
+ * @public
30
+ */
31
+ interface FakeTimersConfig {
32
+ readonly now?: number | Date | TemporalTimelike | undefined;
33
+ /** Jest: globals to leave real. */
34
+ readonly doNotFake?: readonly FakeMethod[] | undefined;
35
+ /** Jest: advance the clock with real time, every 20 ms or the given number of ms. */
36
+ readonly advanceTimers?: boolean | number | undefined;
37
+ /** Jest: how many timers `runAllTimers` runs before it gives up. */
38
+ readonly timerLimit?: number | undefined;
39
+ /** Jest: ask for the legacy implementation, which Provino doesn't have. */
40
+ readonly legacyFakeTimers?: boolean | undefined;
41
+ /** Vitest: the globals to fake. */
42
+ readonly toFake?: readonly FakeMethod[] | undefined;
43
+ /** Vitest: the globals to leave real. */
44
+ readonly toNotFake?: readonly FakeMethod[] | undefined;
45
+ /** Vitest: advance the clock with real time. */
46
+ readonly shouldAdvanceTime?: boolean | undefined;
47
+ /** Vitest: the step of that advance in ms (default 20). */
48
+ readonly advanceTimeDelta?: number | undefined;
49
+ /** Vitest: how many timers `runAllTimers` runs before it gives up. */
50
+ readonly loopLimit?: number | undefined;
51
+ /** Vitest: whether a native timer id passed to a fake `clearTimeout` is cleared (default `true`). */
52
+ readonly shouldClearNativeTimers?: boolean | undefined;
53
+ }
54
+ /**
55
+ * How the clock moves without being told to.
56
+ * @public
57
+ */
58
+ type TimerTickMode = {
59
+ readonly mode: "manual" | "nextAsync";
60
+ } | {
61
+ readonly mode: "interval";
62
+ readonly delta?: number | undefined;
63
+ };
64
+ /**
65
+ * A duration in ms, or a `Temporal.Duration`.
66
+ * @public
67
+ */
68
+ type AdvanceBy = number | TemporalDurationLike;
69
+ /**
70
+ * What `setSystemTime` takes.
71
+ * @public
72
+ */
73
+ type SystemTime = number | Date | TemporalTimelike;
74
+ /**
75
+ * The fake clock of one environment global (Track 4 `FakeClock`). Every difference between Jest's
76
+ * and Vitest's timers is a `TimersPolicy` value; there is one implementation.
77
+ * @public
78
+ */
79
+ interface FakeClock {
80
+ /**
81
+ * Fakes the environment's timers. A second call drops the pending timers first. With
82
+ * `legacyAvailable`, `legacyFakeTimers: true` throws `TIMERS_LEGACY_UNSUPPORTED`.
83
+ */
84
+ install(config?: FakeTimersConfig): void;
85
+ /** Puts the real timers back. Does nothing when they are. */
86
+ uninstall(): void;
87
+ /** Same as `uninstall`: the clock is spent. */
88
+ dispose(): void;
89
+ /** Whether the timers are faked (a clock that only fakes `Date` is not). */
90
+ isInstalled(): boolean;
91
+ /** `advanceTimersByTime`. */
92
+ advanceBy(ms: AdvanceBy): void;
93
+ advanceByAsync(ms: AdvanceBy): Promise<void>;
94
+ /** `advanceTimersToNextTimer`: `steps` timers when the policy honours them, else one. */
95
+ next(steps?: number): void;
96
+ nextAsync(steps?: number): Promise<void>;
97
+ /** `advanceTimersToNextFrame`: to the next 16 ms frame. */
98
+ nextFrame(): void;
99
+ /** `runAllTimers`. */
100
+ runAll(): void;
101
+ runAllAsync(): Promise<void>;
102
+ /** `runOnlyPendingTimers`. */
103
+ runPending(): void;
104
+ runPendingAsync(): Promise<void>;
105
+ /** `runAllTicks`: the jobs a faked `nextTick` or `queueMicrotask` queued. */
106
+ runMicrotasks(): void;
107
+ /** `clearAllTimers`. */
108
+ clearAll(): void;
109
+ /** `getTimerCount`. */
110
+ count(): number;
111
+ /** Drops every timer and keeps the time. */
112
+ reset(): void;
113
+ /**
114
+ * `setSystemTime`. While timers are real it warns and does nothing (`warn-noop`) or fakes `Date`
115
+ * (and `Temporal`) alone (`fake-date-only`).
116
+ */
117
+ setSystemTime(time?: SystemTime): void;
118
+ /** The time `setSystemTime` or `install` set, or `null` when `Date` is real. */
119
+ mockedSystemTime(): Date | null;
120
+ /** `Date.now()` as it was before any install. */
121
+ getRealSystemTime(): number;
122
+ /** The fake time while timers are faked, else the real one. */
123
+ now(): number;
124
+ setTickMode(mode: TimerTickMode): void;
125
+ }
126
+ /**
127
+ * What `createFakeClock` takes besides the environment and the policy.
128
+ * @public
129
+ */
130
+ interface FakeClockOptions {
131
+ /**
132
+ * Binds a callback to the async context it is scheduled in, so one that a later `advance` call
133
+ * fires runs as the test that scheduled it (`CurrentTest.bind`). Without it, a callback runs in
134
+ * its caller's context.
135
+ */
136
+ readonly bind?: (<F extends (...args: never[]) => unknown>(fn: F) => F) | undefined;
137
+ /** The project's `fakeTimers` configuration: what a call's own config is layered over. */
138
+ readonly defaults?: FakeTimersConfig | undefined;
139
+ }
140
+ /**
141
+ * The names `createTimerMembers` defines. Jest's `jest` object has the ones below `getRealSystemTime`
142
+ * that are not Vitest-only; Vitest's `vi` has them all but `now`.
143
+ * @public
144
+ */
145
+ type TimerMemberName = "useFakeTimers" | "useRealTimers" | "runAllTimers" | "runAllTimersAsync" | "runOnlyPendingTimers" | "runOnlyPendingTimersAsync" | "advanceTimersByTime" | "advanceTimersByTimeAsync" | "advanceTimersToNextTimer" | "advanceTimersToNextTimerAsync" | "advanceTimersToNextFrame" | "runAllTicks" | "clearAllTimers" | "getTimerCount" | "setSystemTime" | "getRealSystemTime" | "setTimerTickMode" | "now" | "isFakeTimers" | "getMockedSystemTime";
146
+ /**
147
+ * Creates the clock for one environment global. `withGlobal` reads which timers the global has
148
+ * (`Temporal`, `requestAnimationFrame`, ...) when it is called, so the global must be complete by
149
+ * now. Timers are real until `install`.
150
+ * @public
151
+ */
152
+ export declare function createFakeClock(env: object, policy: TimersPolicy, options?: FakeClockOptions): FakeClock;
153
+ /** The codes a `TimersError` carries. @public */
154
+ type TimersErrorCode = "TIMERS_NOT_FAKED" | "TIMERS_LEGACY_UNSUPPORTED" | "TIMERS_INVALID_TICK_MODE";
155
+ /**
156
+ * An `Error` from the fake clock.
157
+ * @public
158
+ */
159
+ export declare class TimersError extends Error {
160
+ readonly code: TimersErrorCode;
161
+ constructor(code: TimersErrorCode, message: string, options?: ErrorOptions);
162
+ }
163
+ type Member = (...args: never[]) => unknown;
164
+ /**
165
+ * The members, each loosely typed: the object that carries them is the dialect's, and its types are
166
+ * the dialect's own.
167
+ * @public
168
+ */
169
+ type TimerMembers = Readonly<Record<TimerMemberName, Member>>;
170
+ /**
171
+ * Builds the timer members. `clock` returns the clock of the file running now (read when a member
172
+ * is called, because each file has its own); `facade` returns the object that carries the members
173
+ * (read when a member returns, so it may be built after this call).
174
+ * @public
175
+ */
176
+ export declare function createTimerMembers(clock: () => FakeClock, policy: TimersPolicy, facade: () => unknown): TimerMembers;
177
+ export type { AdvanceBy, FakeClock, FakeClockOptions, FakeMethod, FakeTimersConfig, SystemTime, TemporalDurationLike, TemporalTimelike, TimerMemberName, TimerMembers, TimerTickMode, TimersErrorCode };
package/dist/index.js ADDED
@@ -0,0 +1,314 @@
1
+ import { withGlobal } from "@sinonjs/fake-timers";
2
+
3
+ // src/errors.ts
4
+ /**
5
+ * An `Error` from the fake clock.
6
+ * @public
7
+ */
8
+ var TimersError = class extends Error {
9
+ code;
10
+ constructor(code, message, options) {
11
+ super(message, options);
12
+ this.code = code;
13
+ }
14
+ };
15
+
16
+ // src/clock.ts
17
+ /** The globals that queue a callback to run later: the ones a callback is bound to its test at. */
18
+ const SCHEDULERS = [
19
+ "setTimeout",
20
+ "setInterval",
21
+ "setImmediate",
22
+ "requestAnimationFrame",
23
+ "requestIdleCallback",
24
+ "queueMicrotask"
25
+ ];
26
+ /** Node's own microtask-ish queues, left real by default under `toFakeDefault: 'all-but-microtasks'`. */
27
+ const MICROTASKS = /* @__PURE__ */ new Set(["nextTick", "queueMicrotask"]);
28
+ /**
29
+ * Creates the clock for one environment global. `withGlobal` reads which timers the global has
30
+ * (`Temporal`, `requestAnimationFrame`, ...) when it is called, so the global must be complete by
31
+ * now. Timers are real until `install`.
32
+ * @public
33
+ */
34
+ function createFakeClock(env, policy, options = {}) {
35
+ const global = env;
36
+ const sinon = withGlobal(global);
37
+ const allMethods = Object.keys(sinon.timers);
38
+ const RealDate = global.Date;
39
+ const realNow = RealDate.now.bind(RealDate);
40
+ let installed = null;
41
+ let dateOnly = null;
42
+ let clock = null;
43
+ const defaultMethods = () => allMethods.filter((method) => (policy.fakeTemporal || method !== "Temporal") && (policy.toFakeDefault === "all" || !MICROTASKS.has(method)));
44
+ /** Jest's `_toSinonFakeTimersConfig` (`do-not-fake`) or Vitest's `useFakeTimers` (`to-fake`). */
45
+ function toSinonConfig(config, now) {
46
+ if (policy.optionNames === "do-not-fake") {
47
+ const skip = new Set(config.doNotFake ?? []);
48
+ return {
49
+ ...typeof config.advanceTimers === "number" ? { advanceTimeDelta: config.advanceTimers } : {},
50
+ ignoreMissingTimers: true,
51
+ loopLimit: config.timerLimit || policy.loopLimit,
52
+ now: config.now ?? now,
53
+ shouldAdvanceTime: Boolean(config.advanceTimers),
54
+ shouldClearNativeTimers: true,
55
+ toFake: defaultMethods().filter((method) => !skip.has(method))
56
+ };
57
+ }
58
+ let toFake;
59
+ if (config.toFake !== void 0) toFake = [...config.toFake];
60
+ else if (config.toNotFake !== void 0) {
61
+ const skip = new Set(config.toNotFake);
62
+ if (policy.toFakeDefault === "all-but-microtasks") for (const name of MICROTASKS) skip.add(name);
63
+ toFake = defaultMethods().filter((method) => !skip.has(method));
64
+ } else toFake = defaultMethods();
65
+ return {
66
+ ...config.advanceTimeDelta === void 0 ? {} : { advanceTimeDelta: config.advanceTimeDelta },
67
+ ignoreMissingTimers: true,
68
+ loopLimit: config.loopLimit ?? policy.loopLimit,
69
+ now: config.now ?? now,
70
+ ...config.shouldAdvanceTime === void 0 ? {} : { shouldAdvanceTime: config.shouldAdvanceTime },
71
+ shouldClearNativeTimers: config.shouldClearNativeTimers ?? true,
72
+ toFake
73
+ };
74
+ }
75
+ /**
76
+ * Binds every callback the faked schedulers take to the async context it was scheduled in
77
+ * (§6 L793): a fake timer fires from `tick()`, in the caller of `tick()`, where the real one
78
+ * fires in the context of its `setTimeout`. The wrapper keeps the fake's own properties
79
+ * (`.clock`, `util.promisify.custom`), so what looks at them still finds them.
80
+ */
81
+ function bindSchedulers(faked) {
82
+ const { bind } = options;
83
+ if (bind === void 0) return;
84
+ const faking = new Set(faked.methods);
85
+ const wrap = (target, name) => {
86
+ const fake = target[name];
87
+ if (typeof fake !== "function") return;
88
+ const wrapper = function(callback, ...rest) {
89
+ return Reflect.apply(fake, this, [typeof callback === "function" ? bind(callback) : callback, ...rest]);
90
+ };
91
+ for (const key of Reflect.ownKeys(fake)) {
92
+ if (key === "length" || key === "name" || key === "prototype") continue;
93
+ const descriptor = Object.getOwnPropertyDescriptor(fake, key);
94
+ if (descriptor !== void 0) Object.defineProperty(wrapper, key, descriptor);
95
+ }
96
+ target[name] = wrapper;
97
+ };
98
+ for (const name of SCHEDULERS) if (faking.has(name)) wrap(global, name);
99
+ if (faking.has("nextTick") && global.process !== void 0) wrap(global.process, "nextTick");
100
+ }
101
+ function uninstallClock() {
102
+ if (clock !== null) clock.uninstall();
103
+ clock = null;
104
+ installed = null;
105
+ dateOnly = null;
106
+ }
107
+ /** The stack of the call, from the frame above `from` on. */
108
+ function callerStack(from) {
109
+ const error = /* @__PURE__ */ new Error();
110
+ Error.captureStackTrace(error, from);
111
+ return (error.stack ?? "").split("\n").slice(1).join("\n");
112
+ }
113
+ function notFakedText(from) {
114
+ return policy.messages.notFaked.replace("{stack}", () => callerStack(from));
115
+ }
116
+ /** Jest's `_checkFakeTimers` and Vitest's: warn and carry on, or throw. */
117
+ function check() {
118
+ if (installed !== null) return true;
119
+ if (policy.notFaked === "throw") throw new TimersError("TIMERS_NOT_FAKED", notFakedText(check));
120
+ global.console.warn(notFakedText(check));
121
+ return false;
122
+ }
123
+ const live = () => installed;
124
+ const milliseconds = (ms) => typeof ms === "number" ? ms : ms.total({ unit: "millisecond" });
125
+ const timeOf = (time) => time === void 0 ? void 0 : typeof time === "number" ? new Date(time) : "getTime" in time ? new Date(time.getTime()) : new Date(time.epochMilliseconds);
126
+ const self = {
127
+ install(config = {}) {
128
+ const merged = {
129
+ ...options.defaults,
130
+ ...config
131
+ };
132
+ if (policy.legacyAvailable && merged.legacyFakeTimers === true) throw new TimersError("TIMERS_LEGACY_UNSUPPORTED", "Provino does not implement legacy fake timers (`legacyFakeTimers: true`). Use the modern fake timers: drop the option, or `doNotFake` the globals you need real.");
133
+ const fakeDate = dateOnly ?? realNow();
134
+ uninstallClock();
135
+ clock = sinon.install(toSinonConfig(merged, fakeDate));
136
+ installed = clock;
137
+ bindSchedulers(clock);
138
+ },
139
+ uninstall() {
140
+ uninstallClock();
141
+ },
142
+ dispose() {
143
+ uninstallClock();
144
+ },
145
+ isInstalled() {
146
+ return installed !== null;
147
+ },
148
+ advanceBy(ms) {
149
+ if (check()) live().tick(milliseconds(ms));
150
+ },
151
+ async advanceByAsync(ms) {
152
+ if (check()) await live().tickAsync(milliseconds(ms));
153
+ },
154
+ next(steps = 1) {
155
+ if (!check()) return;
156
+ const count = policy.advanceToNextTimerHonorsSteps ? steps : 1;
157
+ const fake = live();
158
+ for (let step = count; step > 0; step--) {
159
+ fake.next();
160
+ fake.tick(0);
161
+ if (fake.countTimers() === 0) break;
162
+ }
163
+ },
164
+ async nextAsync(steps = 1) {
165
+ if (!check()) return;
166
+ const count = policy.advanceToNextTimerHonorsSteps ? steps : 1;
167
+ const fake = live();
168
+ for (let step = count; step > 0; step--) {
169
+ await fake.nextAsync();
170
+ await fake.tickAsync(0);
171
+ if (fake.countTimers() === 0) break;
172
+ }
173
+ },
174
+ nextFrame() {
175
+ if (check()) live().runToFrame();
176
+ },
177
+ runAll() {
178
+ if (check()) live().runAll();
179
+ },
180
+ async runAllAsync() {
181
+ if (check()) await live().runAllAsync();
182
+ },
183
+ runPending() {
184
+ if (check()) live().runToLast();
185
+ },
186
+ async runPendingAsync() {
187
+ if (check()) await live().runToLastAsync();
188
+ },
189
+ runMicrotasks() {
190
+ if (check()) live().runMicrotasks();
191
+ },
192
+ clearAll() {
193
+ if (installed !== null) installed.reset();
194
+ },
195
+ count() {
196
+ return check() ? live().countTimers() : 0;
197
+ },
198
+ reset() {
199
+ if (!check()) return;
200
+ const { now } = live();
201
+ live().reset();
202
+ live().setSystemTime(now);
203
+ },
204
+ setSystemTime(time) {
205
+ if (installed !== null) {
206
+ installed.setSystemTime(timeOf(time));
207
+ return;
208
+ }
209
+ if (policy.setSystemTimeWithoutFakes === "warn-noop") {
210
+ global.console.warn(notFakedText(self.setSystemTime));
211
+ return;
212
+ }
213
+ const date = timeOf(time) ?? new Date(realNow());
214
+ if (dateOnly !== null && clock !== null) {
215
+ dateOnly = date;
216
+ clock.setSystemTime(date);
217
+ return;
218
+ }
219
+ dateOnly = date;
220
+ clock = sinon.install({
221
+ ignoreMissingTimers: true,
222
+ now: date,
223
+ toFake: policy.fakeTemporal ? ["Date", "Temporal"] : ["Date"]
224
+ });
225
+ },
226
+ mockedSystemTime() {
227
+ return installed !== null ? new Date(installed.now) : dateOnly;
228
+ },
229
+ getRealSystemTime() {
230
+ return realNow();
231
+ },
232
+ now() {
233
+ return installed !== null ? installed.now : realNow();
234
+ },
235
+ setTickMode(mode) {
236
+ if (!check()) return;
237
+ if (mode.mode === "manual" || mode.mode === "nextAsync") live().setTickMode({ mode: mode.mode });
238
+ else if (mode.mode === "interval") live().setTickMode(mode.delta === void 0 ? { mode: "interval" } : {
239
+ mode: "interval",
240
+ delta: mode.delta
241
+ });
242
+ else throw new TimersError("TIMERS_INVALID_TICK_MODE", `Invalid tick mode: ${String(mode.mode)}`);
243
+ }
244
+ };
245
+ return self;
246
+ }
247
+
248
+ // src/members.ts
249
+ /** Members that switch timers on or off, which `lifecycle` returns the facade from. */
250
+ const LIFECYCLE = /* @__PURE__ */ new Set([
251
+ "useFakeTimers",
252
+ "useRealTimers",
253
+ "setTimerTickMode"
254
+ ]);
255
+ /** Members that answer a question: they return their answer under every `facadeReturns`. */
256
+ const ANSWERS = /* @__PURE__ */ new Set([
257
+ "getTimerCount",
258
+ "getRealSystemTime",
259
+ "getMockedSystemTime",
260
+ "isFakeTimers",
261
+ "now"
262
+ ]);
263
+ /** Vitest's `setTimerTickMode(mode, interval)` strings, and the sinon names Jest passes. */
264
+ function tickMode(mode, interval) {
265
+ if (typeof mode === "object" && mode !== null) return mode;
266
+ if (mode === "manual") return { mode: "manual" };
267
+ if (mode === "nextTimerAsync") return { mode: "nextAsync" };
268
+ if (mode === "interval") return {
269
+ mode: "interval",
270
+ delta: interval
271
+ };
272
+ throw new TimersError("TIMERS_INVALID_TICK_MODE", `Invalid tick mode: ${String(mode)}`);
273
+ }
274
+ /**
275
+ * Builds the timer members. `clock` returns the clock of the file running now (read when a member
276
+ * is called, because each file has its own); `facade` returns the object that carries the members
277
+ * (read when a member returns, so it may be built after this call).
278
+ * @public
279
+ */
280
+ function createTimerMembers(clock, policy, facade) {
281
+ const chain = (name) => !ANSWERS.has(name) && (policy.facadeReturns === "all" || LIFECYCLE.has(name));
282
+ const syncMember = (name, run) => (...args) => {
283
+ run(...args);
284
+ return chain(name) ? facade() : void 0;
285
+ };
286
+ const asyncMember = (name, run) => async (...args) => {
287
+ await run(...args);
288
+ return chain(name) ? facade() : void 0;
289
+ };
290
+ return {
291
+ useFakeTimers: syncMember("useFakeTimers", (config) => clock().install(config)),
292
+ useRealTimers: syncMember("useRealTimers", () => clock().uninstall()),
293
+ runAllTimers: syncMember("runAllTimers", () => clock().runAll()),
294
+ runAllTimersAsync: asyncMember("runAllTimersAsync", () => clock().runAllAsync()),
295
+ runOnlyPendingTimers: syncMember("runOnlyPendingTimers", () => clock().runPending()),
296
+ runOnlyPendingTimersAsync: asyncMember("runOnlyPendingTimersAsync", () => clock().runPendingAsync()),
297
+ advanceTimersByTime: syncMember("advanceTimersByTime", (ms) => clock().advanceBy(ms)),
298
+ advanceTimersByTimeAsync: asyncMember("advanceTimersByTimeAsync", (ms) => clock().advanceByAsync(ms)),
299
+ advanceTimersToNextTimer: syncMember("advanceTimersToNextTimer", (steps) => clock().next(steps)),
300
+ advanceTimersToNextTimerAsync: asyncMember("advanceTimersToNextTimerAsync", (steps) => clock().nextAsync(steps)),
301
+ advanceTimersToNextFrame: syncMember("advanceTimersToNextFrame", () => clock().nextFrame()),
302
+ runAllTicks: syncMember("runAllTicks", () => clock().runMicrotasks()),
303
+ clearAllTimers: syncMember("clearAllTimers", () => clock().clearAll()),
304
+ getTimerCount: () => clock().count(),
305
+ setSystemTime: syncMember("setSystemTime", (time) => clock().setSystemTime(typeof time === "string" ? new Date(time) : time)),
306
+ getRealSystemTime: () => clock().getRealSystemTime(),
307
+ setTimerTickMode: syncMember("setTimerTickMode", (mode, interval) => clock().setTickMode(tickMode(mode, interval))),
308
+ now: () => clock().now(),
309
+ isFakeTimers: () => clock().isInstalled(),
310
+ getMockedSystemTime: () => clock().mockedSystemTime()
311
+ };
312
+ }
313
+
314
+ export { TimersError, createFakeClock, createTimerMembers };
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "@provino/timers",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-rc.0",
4
+ "description": "Provino's fake timers: one clock over @sinonjs/fake-timers, driven by a dialect's timers policy.",
5
+ "homepage": "https://github.com/pixel-perfect-software/provino#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/pixel-perfect-software/provino/issues"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/pixel-perfect-software/provino.git",
12
+ "directory": "packages/timers"
13
+ },
14
+ "license": "MIT",
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "exports": {
18
+ ".": {
19
+ "provino-source": "./src/index.ts",
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ }
23
+ },
24
+ "files": [
25
+ "dist"
26
+ ],
27
+ "engines": {
28
+ "node": "^22.15.0 || >=24"
29
+ },
30
+ "dependencies": {
31
+ "@provino/types": "0.1.0-rc.0",
32
+ "@sinonjs/fake-timers": "15.4.0"
33
+ },
34
+ "devDependencies": {
35
+ "@provino/policy": "0.1.0-rc.0",
36
+ "@types/jsdom": "30.0.0",
37
+ "@types/sinonjs__fake-timers": "15.0.1",
38
+ "happy-dom": "21.0.4",
39
+ "jsdom": "30.1.3"
40
+ },
41
+ "scripts": {
42
+ "build": "tsdown --config ../../tooling/packaging/tsdown.config.ts",
43
+ "test": "node --test --conditions=provino-source \"src/**/*.test.ts\""
44
+ }
6
45
  }