@graftland/hmr 0.0.0-stage → 0.2.0-beta.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/src/index.ts ADDED
@@ -0,0 +1,578 @@
1
+ /**
2
+ * Hot module replacement for Graft plugins on Node.js.
3
+ */
4
+ // @effect-diagnostics-next-line nodeBuiltinImport:off -- native import resolution must work without requiring a platform layer
5
+ import { realpath } from "node:fs/promises"
6
+ import { fileURLToPath, pathToFileURL } from "node:url"
7
+ import { Graft, Plugin } from "@graftland/graft"
8
+ import {
9
+ Array,
10
+ Cause,
11
+ Data,
12
+ Deferred,
13
+ Effect,
14
+ Exit,
15
+ FiberSet,
16
+ FileSystem,
17
+ HashMap,
18
+ HashSet,
19
+ Option,
20
+ Ref,
21
+ Result,
22
+ String,
23
+ Schema,
24
+ Semaphore,
25
+ Stream,
26
+ Scope,
27
+ } from "effect"
28
+ import type { Duration, PlatformError } from "effect"
29
+ import { changes } from "./internal/changes"
30
+ import {
31
+ isMissingEntry,
32
+ modules,
33
+ RestartRequired,
34
+ type Attempt,
35
+ } from "./internal/modules"
36
+
37
+ export class HmrError extends Schema.TaggedError<
38
+ HmrError,
39
+ { readonly brand: unique symbol }
40
+ >()("HmrError", {
41
+ stage: Schema.Literals(["import", "exports", "closed"]),
42
+ specifier: Schema.String,
43
+ cause: Schema.Unknown,
44
+ }) {
45
+ override get message(): string {
46
+ return `HMR ${this.stage} failed for ${this.specifier || "the closed session"}`
47
+ }
48
+ }
49
+
50
+ export type WatchResult = Data.TaggedEnum<{
51
+ Reloaded: { readonly entries: ReadonlyArray<string> }
52
+ Skipped: {
53
+ readonly modules: ReadonlyArray<string>
54
+ readonly reason:
55
+ "restart-required" | "ambiguous-exports" | "identity-conflict"
56
+ }
57
+ Failed: { readonly cause: Cause.Cause<HmrError> }
58
+ }>
59
+
60
+ export const WatchResult = Data.taggedEnum<WatchResult>()
61
+
62
+ export type ReloadResult = Exclude<WatchResult, { readonly _tag: "Failed" }>
63
+
64
+ export interface Options {
65
+ /** Application module URL, usually import.meta.url; used for bare and relative resolution. */
66
+ readonly base: string
67
+ /** Files to version. Defaults to file URLs outside node_modules. Entries are always included. */
68
+ readonly include?: (url: string) => boolean
69
+ }
70
+
71
+ export interface WatchOptions extends FileSystem.WatchOptions {
72
+ readonly debounce?: Duration.Input
73
+ /** Receives an absolute file path; applies to native events and reconciliation. */
74
+ readonly filter?: (path: string) => boolean
75
+ }
76
+
77
+ /** Separates retry observations from an importer's temporary resource scope. */
78
+ export interface ImportOptions {
79
+ readonly observationScope: Scope.Scope
80
+ }
81
+
82
+ export interface Hmr {
83
+ /** Keeps imported entries registered until this HMR session closes. */
84
+ readonly importer: (specifier: string) => Promise<unknown>
85
+ /** Registers an observation lease in observationScope, or the caller's scope when omitted. */
86
+ readonly importerScoped: (
87
+ specifier: string,
88
+ options?: ImportOptions,
89
+ ) => Effect.Effect<unknown, HmrError, Scope.Scope>
90
+ /** Imports every entry before replacing anything. Activation failures belong to Graft. */
91
+ readonly reload: Effect.Effect<ReloadResult, HmrError>
92
+ /**
93
+ * Consuming this stream installs watchers and checks loaded module contents once
94
+ * per second to recover missed events. Known native loading limitations emit
95
+ * Skipped even without a file event. The consumer owns the stream's lifetimes.
96
+ */
97
+ readonly watch: (
98
+ paths: ReadonlyArray<string>,
99
+ options?: WatchOptions,
100
+ ) => Stream.Stream<
101
+ WatchResult,
102
+ PlatformError.PlatformError,
103
+ FileSystem.FileSystem
104
+ >
105
+ }
106
+
107
+ /**
108
+ * Installs Node module hooks until the enclosing scope closes. Module evaluation
109
+ * must be side-effect free. Versioned ESM cache entries are not reclaimed.
110
+ */
111
+ export const make = (
112
+ options: Options,
113
+ ): Effect.Effect<Hmr, never, Graft.Graft | Scope.Scope> =>
114
+ Effect.gen(function* () {
115
+ const graft = yield* Graft.Graft
116
+ const semaphore = yield* Semaphore.make(1)
117
+ // A lease owns both the running graph and its latest uncommitted attempt.
118
+ const owners = yield* Ref.make(
119
+ HashMap.empty<
120
+ symbol,
121
+ {
122
+ readonly active: Option.Option<Attempt>
123
+ readonly pending: Option.Option<Attempt>
124
+ }
125
+ >(),
126
+ )
127
+ const closed = yield* Ref.make(false)
128
+ const session = yield* Effect.scope
129
+ // Transfer the complete Exit before restoring interruption. Effect may replace
130
+ // a failed masked operation with pending interruption at that boundary.
131
+ const preserveExit = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
132
+ Effect.gen(function* () {
133
+ const completed = yield* Deferred.make<Exit.Exit<A, E>>()
134
+ return yield* effect.pipe(
135
+ Effect.exit,
136
+ Effect.tap((exit) => Deferred.succeed(completed, exit)),
137
+ Effect.uninterruptible,
138
+ Effect.flatten,
139
+ Effect.onExit((exit) =>
140
+ Effect.gen(function* () {
141
+ if (Exit.isSuccess(exit) || !Cause.hasInterrupts(exit.cause))
142
+ return
143
+ const saved = yield* Deferred.poll(completed)
144
+ if (Option.isNone(saved)) return
145
+ const original = yield* saved.value
146
+ if (Exit.isFailure(original))
147
+ yield* Effect.logError(
148
+ "HMR operation failed during cancellation",
149
+ original.cause,
150
+ )
151
+ }),
152
+ ),
153
+ )
154
+ })
155
+ // Native imports cannot be cancelled: keep the lock until their promises settle.
156
+ const serial = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
157
+ effect.pipe(preserveExit, semaphore.withPermits(1))
158
+ const hooks = yield* Effect.acquireRelease(
159
+ Effect.sync(() =>
160
+ modules(
161
+ options.base,
162
+ options.include ??
163
+ ((url) =>
164
+ !String.includes("/node_modules/")(new URL(url).pathname)),
165
+ ),
166
+ ),
167
+ (hooks) =>
168
+ serial(
169
+ Ref.set(closed, true).pipe(Effect.andThen(Effect.sync(hooks.close))),
170
+ ),
171
+ )
172
+ const state = yield* Ref.make({
173
+ generation: hooks.prepare(),
174
+ entries: HashMap.empty<
175
+ string,
176
+ {
177
+ readonly plugin: Plugin.Plugin
178
+ readonly leases: HashSet.HashSet<symbol>
179
+ }
180
+ >(),
181
+ })
182
+ // Stop Promise-backed operations before releasing their leases. Otherwise
183
+ // a lease finalizer could wait on an import before its owner interrupts it.
184
+ const imports = yield* Scope.fork(session)
185
+ const run = yield* FiberSet.makeRuntimePromise<never, unknown, HmrError>()
186
+ const closedError = () =>
187
+ HmrError.make({
188
+ stage: "closed",
189
+ specifier: "",
190
+ cause: "HMR scope is closed",
191
+ })
192
+ const checkOpen = Ref.get(closed).pipe(
193
+ Effect.flatMap((closed) =>
194
+ closed ? Effect.fail(closedError()) : Effect.void,
195
+ ),
196
+ )
197
+ const physicalTarget = (request: string) =>
198
+ Effect.tryPromise({
199
+ try: () => realpath(fileURLToPath(request)),
200
+ catch: (cause) =>
201
+ HmrError.make({ stage: "import", specifier: request, cause }),
202
+ }).pipe(
203
+ Effect.map((path) => pathToFileURL(path).href),
204
+ Effect.catchIf(
205
+ (error) => isMissingEntry(request, error.cause),
206
+ () => Effect.undefined,
207
+ ),
208
+ )
209
+ const changedResolution = Effect.fnUntraced(function* (
210
+ attempt: Pick<Attempt, "url" | "request">,
211
+ ) {
212
+ if (attempt.request === undefined) return Option.none<string>()
213
+ const request = attempt.request
214
+ const expected = pathToFileURL(fileURLToPath(attempt.url)).href
215
+ const actual = yield* physicalTarget(request)
216
+ if (actual === expected) return Option.none<string>()
217
+ // If both paths disappeared, this is ordinary entry deletion. A
218
+ // missing link with a surviving old target must never reload that target.
219
+ if (actual === undefined) {
220
+ const remaining = yield* physicalTarget(attempt.url)
221
+ if (remaining === undefined) return Option.none<string>()
222
+ }
223
+ return Option.some(request)
224
+ })
225
+
226
+ const changedResolutions = Ref.get(owners).pipe(
227
+ Effect.flatMap((owners) =>
228
+ Effect.forEach(
229
+ hooks.resolutions(
230
+ Array.flatMap(HashMap.toValues(owners), (owner) =>
231
+ Array.getSomes([owner.active, owner.pending]),
232
+ ),
233
+ ),
234
+ changedResolution,
235
+ ),
236
+ ),
237
+ Effect.map((changes) =>
238
+ Array.fromIterable(HashSet.fromIterable(Array.getSomes(changes))),
239
+ ),
240
+ )
241
+ const load = Effect.fnUntraced(function* (specifier: string) {
242
+ const namespace = yield* Effect.tryPromise({
243
+ try: () => import(/* @vite-ignore */ hooks.request(specifier)),
244
+ catch: (cause) => HmrError.make({ stage: "import", specifier, cause }),
245
+ })
246
+ const plugin = Plugin.fromModule(namespace)
247
+ if (Option.isNone(plugin))
248
+ return yield* HmrError.make({
249
+ stage: "exports",
250
+ specifier,
251
+ cause: "Expected a default or named plugin export",
252
+ })
253
+ const url = yield* Effect.fromOption(hooks.resolved()).pipe(
254
+ Effect.mapError((cause) =>
255
+ HmrError.make({ stage: "import", specifier, cause }),
256
+ ),
257
+ )
258
+ const request = hooks.fileRequest(specifier)
259
+ const attempt = {
260
+ url,
261
+ ...Option.match(request, {
262
+ onNone: () => ({}),
263
+ onSome: (request) => ({ request }),
264
+ }),
265
+ }
266
+ const changed = yield* changedResolution(attempt)
267
+ if (Option.isSome(changed))
268
+ return yield* HmrError.make({
269
+ stage: "import",
270
+ specifier,
271
+ cause: RestartRequired.make({ url: changed.value }),
272
+ })
273
+ return { namespace, plugin: plugin.value, url }
274
+ })
275
+ const importWithLease = (specifier: string) =>
276
+ Effect.acquireRelease(
277
+ serial(
278
+ Effect.gen(function* () {
279
+ yield* checkOpen
280
+ const current = yield* Ref.get(state)
281
+ hooks.start(current.generation)
282
+ // Acquire an owner for either Exit. Rethrow only after its finalizer
283
+ // is registered, so failed imports remain available for scoped retry.
284
+ const exit = yield* Effect.exit(load(specifier))
285
+ const token: symbol = Symbol()
286
+ const root = Option.orElse(hooks.resolved(), () =>
287
+ String.startsWith("file:")(specifier)
288
+ ? Option.some(specifier)
289
+ : Option.none(),
290
+ )
291
+ const attempt = Option.map(root, (url) => ({
292
+ url,
293
+ generation: current.generation,
294
+ ...Option.match(hooks.fileRequest(specifier), {
295
+ onNone: () => ({}),
296
+ onSome: (request) => ({ request }),
297
+ }),
298
+ }))
299
+ yield* Ref.update(
300
+ owners,
301
+ HashMap.set(token, {
302
+ active: Exit.isSuccess(exit) ? attempt : Option.none(),
303
+ pending: Exit.isFailure(exit) ? attempt : Option.none(),
304
+ }),
305
+ )
306
+ if (Exit.isSuccess(exit)) {
307
+ const entry = exit.value
308
+ const previous = HashMap.get(current.entries, entry.url)
309
+ const leases = Option.match(previous, {
310
+ onNone: () => HashSet.empty<symbol>(),
311
+ onSome: (entry) => entry.leases,
312
+ })
313
+ yield* Ref.set(state, {
314
+ ...current,
315
+ entries: HashMap.set(current.entries, entry.url, {
316
+ plugin: entry.plugin,
317
+ leases: HashSet.add(leases, token),
318
+ }),
319
+ })
320
+ }
321
+ return { token, exit: Exit.map(exit, (entry) => entry.namespace) }
322
+ }).pipe(Effect.ensuring(Effect.sync(hooks.discard))),
323
+ ),
324
+ ({ token }) =>
325
+ serial(
326
+ Effect.gen(function* () {
327
+ yield* Ref.update(owners, HashMap.remove(token))
328
+ yield* Ref.update(state, (current) => ({
329
+ ...current,
330
+ entries: HashMap.filterMap(current.entries, (entry) => {
331
+ const leases = HashSet.remove(entry.leases, token)
332
+ return HashSet.size(leases) === 0
333
+ ? Result.fail(undefined)
334
+ : Result.succeed({ ...entry, leases })
335
+ }),
336
+ }))
337
+ }),
338
+ ),
339
+ ).pipe(
340
+ Effect.flatMap(({ exit }) => exit),
341
+ preserveExit,
342
+ )
343
+
344
+ const importerScoped: Hmr["importerScoped"] = (specifier, options) =>
345
+ options === undefined
346
+ ? importWithLease(specifier)
347
+ : importWithLease(specifier).pipe(
348
+ Scope.provide(options.observationScope),
349
+ )
350
+
351
+ const importer = (specifier: string): Promise<unknown> =>
352
+ // A closed FiberSet interrupts new work before checkOpen can execute.
353
+ Ref.getUnsafe(closed)
354
+ ? Promise.reject(closedError())
355
+ : run(
356
+ importerScoped(specifier).pipe(
357
+ Effect.provideService(Scope.Scope, imports),
358
+ ),
359
+ )
360
+
361
+ const unsupportedModules = Ref.get(state).pipe(
362
+ Effect.map(({ generation, entries }) =>
363
+ hooks.unsupported(
364
+ generation,
365
+ Array.fromIterable(HashMap.keys(entries)),
366
+ ),
367
+ ),
368
+ )
369
+
370
+ const reload = serial(
371
+ Effect.gen(function* () {
372
+ yield* checkOpen
373
+ const changed = yield* changedResolutions
374
+ if (changed.length > 0)
375
+ return WatchResult.Skipped({
376
+ reason: "restart-required",
377
+ modules: changed,
378
+ })
379
+ const { entries } = yield* Ref.get(state)
380
+ const unsupported = yield* unsupportedModules
381
+ if (HashSet.size(unsupported) > 0)
382
+ return WatchResult.Skipped({
383
+ modules: Array.fromIterable(unsupported),
384
+ reason: "restart-required",
385
+ })
386
+ // Advance even without entries so retries bypass cached failed imports.
387
+ const candidate = hooks.prepare()
388
+ hooks.start(candidate, true)
389
+ return yield* Effect.gen(function* () {
390
+ const loaded = yield* Effect.forEach(entries, ([url, previous]) =>
391
+ Ref.update(
392
+ owners,
393
+ HashMap.map((owner, token) =>
394
+ HashSet.has(previous.leases, token)
395
+ ? {
396
+ ...owner,
397
+ pending: Option.map(owner.active, (attempt) => ({
398
+ ...attempt,
399
+ url,
400
+ generation: candidate,
401
+ })),
402
+ }
403
+ : owner,
404
+ ),
405
+ ).pipe(
406
+ Effect.andThen(load(url)),
407
+ Effect.map((entry) =>
408
+ Option.some({
409
+ url,
410
+ previous: previous.plugin,
411
+ leases: previous.leases,
412
+ plugin: entry.plugin,
413
+ }),
414
+ ),
415
+ Effect.catchIf(
416
+ (error) =>
417
+ error.stage === "import" && isMissingEntry(url, error.cause),
418
+ () => Effect.succeedNone,
419
+ ),
420
+ ),
421
+ )
422
+ const candidates = Array.getSomes(loaded)
423
+ const alternatives = Array.reduce(
424
+ candidates,
425
+ HashMap.empty<Plugin.Plugin, HashSet.HashSet<Plugin.Plugin>>(),
426
+ (groups, { previous, plugin }) =>
427
+ HashMap.set(
428
+ groups,
429
+ previous,
430
+ HashSet.add(
431
+ Option.getOrElse(
432
+ HashMap.get(groups, previous),
433
+ HashSet.empty<Plugin.Plugin>,
434
+ ),
435
+ plugin,
436
+ ),
437
+ ),
438
+ )
439
+ const ambiguous = Array.filter(candidates, ({ previous }) =>
440
+ Option.exists(
441
+ HashMap.get(alternatives, previous),
442
+ (plugins) => HashSet.size(plugins) > 1,
443
+ ),
444
+ )
445
+ if (ambiguous.length > 0)
446
+ return WatchResult.Skipped({
447
+ reason: "ambiguous-exports",
448
+ modules: Array.map(ambiguous, ({ url }) => url),
449
+ })
450
+ const next = HashMap.fromIterable(
451
+ Array.map(
452
+ candidates,
453
+ ({ url, plugin, leases }) => [url, { plugin, leases }] as const,
454
+ ),
455
+ )
456
+ const pairs = Array.map(
457
+ candidates,
458
+ ({ previous, plugin }) => [previous, plugin] as const,
459
+ )
460
+ const changed = yield* changedResolutions
461
+ if (changed.length > 0)
462
+ return WatchResult.Skipped({
463
+ reason: "restart-required",
464
+ modules: changed,
465
+ })
466
+ const replacement = yield* Graft.replace(pairs).pipe(
467
+ Effect.provideService(Graft.Graft, graft),
468
+ Effect.result,
469
+ )
470
+ if (Result.isFailure(replacement))
471
+ return WatchResult.Skipped({
472
+ reason: "identity-conflict",
473
+ modules: Array.filterMap(candidates, ({ url }, index) =>
474
+ Array.contains(replacement.failure.indices, index)
475
+ ? Result.succeed(url)
476
+ : Result.fail(undefined),
477
+ ),
478
+ })
479
+ yield* Ref.update(owners, (owners) =>
480
+ Array.reduce(candidates, owners, (owners, { url, leases }) =>
481
+ HashMap.map(owners, (owner, token) =>
482
+ HashSet.has(leases, token)
483
+ ? {
484
+ active: Option.map(owner.pending, (attempt) => ({
485
+ ...attempt,
486
+ url,
487
+ generation: candidate,
488
+ })),
489
+ pending: Option.none(),
490
+ }
491
+ : owner,
492
+ ),
493
+ ),
494
+ )
495
+ yield* Ref.set(state, { entries: next, generation: candidate })
496
+ return WatchResult.Reloaded({
497
+ entries: Array.fromIterable(HashMap.keys(next)),
498
+ })
499
+ }).pipe(
500
+ Effect.catchIf(
501
+ (error): error is HmrError & { readonly cause: RestartRequired } =>
502
+ Schema.is(RestartRequired)(error.cause),
503
+ (error) =>
504
+ Effect.succeed(
505
+ WatchResult.Skipped({
506
+ modules: Array.fromIterable(
507
+ HashSet.add(hooks.unsupported(candidate), error.cause.url),
508
+ ),
509
+ reason: "restart-required",
510
+ }),
511
+ ),
512
+ ),
513
+ Effect.ensuring(Effect.sync(hooks.discard)),
514
+ )
515
+ }),
516
+ )
517
+ return {
518
+ importer,
519
+ importerScoped,
520
+ reload,
521
+ watch: (paths, watchOptions) =>
522
+ paths.length === 0
523
+ ? Stream.empty
524
+ : changes(
525
+ (use) =>
526
+ Ref.get(owners).pipe(
527
+ Effect.map((owners) =>
528
+ hooks.files([
529
+ ...Array.getSomes(
530
+ Array.map(
531
+ HashMap.toValues(owners),
532
+ (owner) => owner.active,
533
+ ),
534
+ ),
535
+ ...Array.getSomes(
536
+ Array.map(
537
+ HashMap.toValues(owners),
538
+ (owner) => owner.pending,
539
+ ),
540
+ ),
541
+ ]),
542
+ ),
543
+ Effect.flatMap(use),
544
+ // Hold ownership through the reads, so release cannot leave
545
+ // an in-flight snapshot reading a retired path.
546
+ semaphore.withPermits(1),
547
+ ),
548
+ paths,
549
+ watchOptions,
550
+ ).pipe(
551
+ Stream.debounce(watchOptions?.debounce ?? "50 millis"),
552
+ Stream.mapEffect(() =>
553
+ Effect.map(Effect.exit(reload), (exit): WatchResult =>
554
+ Exit.isSuccess(exit)
555
+ ? exit.value
556
+ : WatchResult.Failed({ cause: exit.cause }),
557
+ ),
558
+ ),
559
+ // Native caches may hide both dependency edges and the first save.
560
+ // Report known restart requirements independently of filesystem events.
561
+ Stream.merge(
562
+ Stream.tick("1 second").pipe(
563
+ Stream.mapEffect(() =>
564
+ unsupportedModules.pipe(semaphore.withPermits(1)),
565
+ ),
566
+ Stream.changes,
567
+ Stream.filter((modules) => HashSet.size(modules) > 0),
568
+ Stream.map((modules) =>
569
+ WatchResult.Skipped({
570
+ reason: "restart-required",
571
+ modules: Array.fromIterable(modules),
572
+ }),
573
+ ),
574
+ ),
575
+ ),
576
+ ),
577
+ }
578
+ })