@pentacore/vite-plugin-laravel-typefinder 4.0.2 → 4.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @pentacore/vite-plugin-laravel-typefinder
 
-A Vite plugin that automatically runs `php artisan typefinder:generate` on build start and re-runs it (debounced) whenever watched PHP files change via HMR.
+A Vite plugin that keeps your TypeScript type definitions in sync with your Laravel codebase. In development, it spawns a persistent `typefinder:watch` process that regenerates only the `.d.ts` files affected by each edit — typical latency is 20-60ms per change. In production builds, it runs a one-shot `typefinder:generate` before bundling.
 
-> **This plugin is a companion to the [`pentacore/laravel-typefinder`](https://packagist.org/packages/pentacore/laravel-typefinder) Composer package — you must install that first.** The plugin's only job is to invoke its artisan command at the right moments; all type generation lives in the PHP package. Installing this npm package without the Composer package will result in the plugin failing to find `php artisan typefinder:generate`.
+> **This plugin is a companion to the [`pentacore/laravel-typefinder`](https://packagist.org/packages/pentacore/laravel-typefinder) Composer package — you must install that first.**
 
 ## Requirements
 
@@ -28,31 +28,69 @@ import typefinder from '@pentacore/vite-plugin-laravel-typefinder';
 export default defineConfig({
     plugins: [
         laravel({ input: ['resources/js/app.js'] }),
-        typefinder({
-            // All options are optional — defaults shown below
-            command: 'php artisan typefinder:generate',
-            watch: ['app/Models/**/*.php', 'app/Enums/**/*.php', 'app/Http/Requests/**/*.php'],
-            debounceMs: 100,
-        }),
+        typefinder(),   // zero-config — all options are optional
     ],
 });
 ```
 
-## Options
+## Configuration
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `command` | `string` | `'php artisan typefinder:generate'` | The shell command to run for type generation |
-| `watch` | `string[]` | `['app/Models/**/*.php', 'app/Enums/**/*.php', 'app/Http/Requests/**/*.php']` | Glob patterns for files that trigger re-generation on HMR change |
-| `debounceMs` | `number` | `100` | Milliseconds to wait after a file change before running the command, to coalesce rapid saves |
+All options are optional. Defaults work for a standard Laravel project with `php` on `$PATH`.
+
+```ts
+typefinder({
+    // Shell command for the long-lived watcher process.
+    // Override for Sail/Herd/Docker.
+    command: 'php artisan typefinder:watch',
+
+    // Shell command used in `vite build` (one-shot, no watcher).
+    // Set to `false` to skip generation entirely in build mode.
+    buildCommand: 'php artisan typefinder:generate --json',
+
+    // Override the paths the plugin watches. When unset (the default),
+    // paths come from the watcher's handshake, which mirrors your
+    // config/typefinder.php. Provide absolute paths.
+    watch: undefined,
+
+    // Debounce window (ms) for coalescing HMR events.
+    debounceMs: 100,
+
+    // How long to wait for the watcher's `ready` handshake before failing.
+    startupTimeoutMs: 10_000,
+
+    // Grace period between SIGTERM and SIGKILL when shutting down.
+    killTimeoutMs: 2_000,
+});
+```
+
+### Runtime-specific examples
+
+```ts
+// Laravel Sail
+typefinder({ command: './vendor/bin/sail artisan typefinder:watch' })
+
+// Laravel Herd
+typefinder({ command: 'herd php artisan typefinder:watch' })
+
+// Docker Compose
+typefinder({ command: 'docker compose exec app php artisan typefinder:watch' })
+```
 
 ## Behavior
 
-**On `buildStart`:** The command runs once synchronously before bundling begins, ensuring your TypeScript types are always fresh before the build processes them.
+**Development (`vite dev`):** The plugin spawns `typefinder:watch` — a persistent Laravel process that boots once and accepts incremental regeneration requests over NDJSON. When a `.php` file matching the watched paths changes via HMR, the plugin sends the changed file paths to the watcher, which re-extracts only those files and rewrites only the affected `.d.ts` outputs. Multiple rapid edits within the debounce window are coalesced into a single request.
+
+The watched paths are read from the watcher's startup handshake, which mirrors your `config/typefinder.php`. If you enable Inertia pages or broadcasting in the config, the plugin automatically watches those directories too — no manual `watch` array needed.
+
+**Production (`vite build`):** No watcher. The plugin runs `typefinder:generate --json` once in `buildStart` and fails the build on non-zero exit. Set `buildCommand: false` to skip generation entirely (e.g. for pre-built containers without a PHP runtime).
+
+**Shutdown:** The watcher is killed on `closeBundle` and on process exit. If the watcher dies mid-session (PHP fatal, OOM), the plugin logs the error and stops regenerating — restart the dev server to recover.
 
-**On HMR file changes:** When a file matching one of the `watch` patterns changes, the plugin schedules a debounced run. If the command is already running when the timer fires, the new run is queued — only one run is ever active at a time, but at most one follow-up run will be queued to pick up any changes that arrived mid-run. This prevents stale types while avoiding unbounded queuing.
+### Migration from v4.0
 
-The plugin relies on Typefinder's selective-write behaviour: the PHP command re-extracts the full type graph on every run, but only files whose content has actually changed are rewritten on disk — meaning HMR in your frontend is not needlessly triggered for unchanged types.
+- `command` default changed from `typefinder:generate` to `typefinder:watch`. If you explicitly set `command`, update it — dev mode requires the long-lived watcher.
+- `watch` default changed from a hardcoded path list to `undefined`, meaning "use whatever the watcher reports". Existing explicit `watch: [...]` configurations keep working unchanged.
+- Regenerations now run against a persistent Laravel boot via NDJSON. Typical edit latency drops from ~300-500ms to ~20-60ms.
 
 ## Alternative install (from vendor)
 

package/dist/index.d.ts

@@ -1,77 +1 @@
-import { Plugin } from 'vite';
-
-/**
- * Options for the `typefinder` Vite plugin.
- *
- * All fields are optional — the defaults work for a standard Laravel project
- * running PHP directly. Override `command` when using Sail, Herd, Docker, or
- * any other PHP runtime wrapper. Extend `watch` when you use Typefinder's
- * resource / page / broadcast features so the plugin regenerates on those
- * file changes too.
- */
-interface TypefinderOptions {
-    /**
-     * Glob patterns (relative to the Vite project root) whose changes should
-     * trigger a regeneration. Matched against each HMR update's file path.
-     *
-     * The default covers models, enums, and form requests — the always-on
-     * Typefinder categories. If you enable optional categories (Inertia pages,
-     * broadcasting) or use JSON resources, extend the list so updates on
-     * those directories also re-run the generator.
-     *
-     * @default ['app/Models/** /*.php', 'app/Enums/** /*.php', 'app/Http/Requests/** /*.php']
-     */
-    watch?: string[];
-    /**
-     * Shell command used to regenerate types. Customize for non-standard
-     * PHP runtimes:
-     *
-     * - Sail: `'./vendor/bin/sail artisan typefinder:generate'`
-     * - Herd: `'herd php artisan typefinder:generate'`
-     * - Docker: `'docker compose exec app php artisan typefinder:generate'`
-     *
-     * @default 'php artisan typefinder:generate'
-     */
-    command?: string;
-    /**
-     * Debounce window in milliseconds. When multiple files change within this
-     * window the plugin coalesces them into a single regeneration. Keep small
-     * for fast feedback; raise if your editor triggers noisy saves.
-     *
-     * @default 100
-     */
-    debounceMs?: number;
-}
-/**
- * Vite plugin that runs `php artisan typefinder:generate` automatically —
- * once at `buildStart`, and again on every HMR update whose file path
- * matches any pattern in {@link TypefinderOptions.watch}.
- *
- * Install the Composer package `pentacore/laravel-typefinder` in your Laravel
- * app, then register this plugin in `vite.config.ts`:
- *
- * ```ts
- * import { defineConfig } from 'vite';
- * import laravel from 'laravel-vite-plugin';
- * import typefinder from '@pentacore/vite-plugin-laravel-typefinder';
- *
- * export default defineConfig({
- *   plugins: [
- *     laravel({ input: ['resources/js/app.ts'] }),
- *     typefinder(),
- *   ],
- * });
- * ```
- *
- * Regenerations are debounced and serialized — concurrent triggers coalesce
- * into at most one in-flight run plus one queued run. The plugin uses Vite's
- * `enforce: 'pre'` ordering so types are fresh before other plugins inspect
- * them.
- *
- * @param options Plugin options. See {@link TypefinderOptions}.
- * @returns A Vite plugin.
- */
-declare const typefinder: ({ watch, command, debounceMs, }?: TypefinderOptions) => Plugin;
-
-export { typefinder as default, typefinder };
-export type { TypefinderOptions };
+export { }

package/dist/index.js

@@ -0,0 +1,245 @@
+var $ = Object.defineProperty;
+var v = (l, s, t) => s in l ? $(l, s, { enumerable: !0, configurable: !0, writable: !0, value: t }) : l[s] = t;
+var p = (l, s, t) => v(l, typeof s != "symbol" ? s + "" : s, t);
+import { spawn as E, exec as S } from "node:child_process";
+import { promisify as b } from "node:util";
+import T from "picomatch";
+import { EventEmitter as R } from "node:events";
+const k = (l) => {
+  if (l.length === 0)
+    return () => !1;
+  const s = l.map((r) => `${r.replace(/\\/g, "/").replace(/\/$/, "")}/**/*.php`), t = T(s, { dot: !0 });
+  return (r) => {
+    const i = r.replace(/\\/g, "/");
+    return t(i);
+  };
+};
+class y extends R {
+  constructor(t, r, i) {
+    var a, d;
+    super();
+    p(this, "handshake");
+    p(this, "child");
+    p(this, "killTimeoutMs");
+    p(this, "buffer", "");
+    p(this, "inflight", null);
+    p(this, "nextBatch", null);
+    p(this, "nextResolvers", []);
+    p(this, "idCounter", 0);
+    p(this, "_dead", !1);
+    this.child = t, this.handshake = r, this.killTimeoutMs = i, (a = t.stdout) == null || a.on("data", (e) => {
+      this.onStdout(typeof e == "string" ? e : e.toString("utf8"));
+    }), (d = t.stderr) == null || d.on("data", (e) => {
+      const c = (typeof e == "string" ? e : e.toString("utf8")).trimEnd();
+      c !== "" && process.stderr.write(`[typefinder] ${c}
+`);
+    }), t.on("exit", (e, c) => {
+      this._dead = !0;
+      const f = c ? `signal ${c}` : `exit code ${e ?? "null"}`;
+      this.emit("died", f), this.inflight && (this.inflight.reject(new Error(`watcher died (${f})`)), this.inflight = null);
+      for (const m of this.nextResolvers)
+        m.reject(new Error(`watcher died (${f})`));
+      this.nextResolvers = [], this.nextBatch = null;
+    });
+  }
+  get dead() {
+    return this._dead;
+  }
+  static async spawn(t) {
+    const i = (t.spawnFn ?? ((a, d, e) => E(a, d, e)))(t.command, [], { cwd: t.cwd, shell: !0 });
+    return new Promise((a, d) => {
+      var w;
+      let e = "";
+      const c = (h) => {
+        var u;
+        e += typeof h == "string" ? h : h.toString("utf8");
+        const n = e.indexOf(`
+`);
+        if (n === -1) return;
+        const o = e.slice(0, n);
+        e = e.slice(n + 1), clearTimeout(m), (u = i.stdout) == null || u.off("data", c), i.off("exit", f);
+        try {
+          const g = JSON.parse(o);
+          if (g.type !== "ready")
+            throw new Error("expected ready, got " + g.type);
+          const x = new y(i, g, t.killTimeoutMs ?? 2e3);
+          e.length > 0 && x.onStdout(e), a(x);
+        } catch (g) {
+          i.kill("SIGTERM"), d(new Error(`malformed handshake: ${g.message}`));
+        }
+      }, f = (h, n) => {
+        var o;
+        clearTimeout(m), (o = i.stdout) == null || o.off("data", c), d(new Error(`watcher exited before handshake (code=${h}, signal=${n})`));
+      }, m = setTimeout(() => {
+        var h;
+        (h = i.stdout) == null || h.off("data", c), i.off("exit", f), i.kill("SIGTERM"), d(new Error(`watcher startup timeout after ${t.startupTimeoutMs}ms`));
+      }, t.startupTimeoutMs);
+      (w = i.stdout) == null || w.on("data", c), i.on("exit", f);
+    });
+  }
+  async regen(t) {
+    if (this._dead)
+      throw new Error("watcher is dead");
+    if (!this.inflight)
+      return this.dispatch(t);
+    this.nextBatch || (this.nextBatch = /* @__PURE__ */ new Set());
+    for (const r of t)
+      this.nextBatch.add(r);
+    return new Promise((r, i) => {
+      this.nextResolvers.push({ resolve: r, reject: i });
+    });
+  }
+  dispatch(t) {
+    var a;
+    const r = `r${++this.idCounter}`, i = { type: "regen", id: r, paths: t };
+    return (a = this.child.stdin) == null || a.write(JSON.stringify(i) + `
+`), new Promise((d, e) => {
+      this.inflight = { id: r, resolve: d, reject: e };
+    });
+  }
+  onStdout(t) {
+    this.buffer += t;
+    let r;
+    for (; (r = this.buffer.indexOf(`
+`)) !== -1; ) {
+      const i = this.buffer.slice(0, r);
+      this.buffer = this.buffer.slice(r + 1), i.trim() !== "" && this.handleLine(i);
+    }
+  }
+  handleLine(t) {
+    let r;
+    try {
+      r = JSON.parse(t);
+    } catch {
+      process.stderr.write(`[typefinder] unparseable line: ${t}
+`);
+      return;
+    }
+    if (r.type === "regen.done" || r.type === "regen.error") {
+      if (!this.inflight || "id" in r && this.inflight.id !== r.id)
+        return;
+      const i = this.inflight;
+      this.inflight = null, r.type === "regen.done" ? i.resolve(r) : i.reject(new Error(r.message)), this.drainQueued();
+    }
+  }
+  drainQueued() {
+    if (!this.nextBatch || this.nextResolvers.length === 0) return;
+    const t = Array.from(this.nextBatch), r = [...this.nextResolvers];
+    this.nextBatch = null, this.nextResolvers = [], this.dispatch(t).then(
+      (i) => r.forEach((a) => a.resolve(i)),
+      (i) => r.forEach((a) => a.reject(i))
+    );
+  }
+  async kill() {
+    this._dead || await new Promise((t) => {
+      const r = setTimeout(() => {
+        this._dead || this.child.kill("SIGKILL");
+      }, this.killTimeoutMs);
+      this.child.once("exit", () => {
+        clearTimeout(r), t();
+      }), this.child.kill("SIGTERM");
+    });
+  }
+}
+const M = b(S), G = ({
+  command: l = "php artisan typefinder:watch",
+  buildCommand: s = "php artisan typefinder:generate --json",
+  watch: t,
+  debounceMs: r = 100,
+  startupTimeoutMs: i = 1e4,
+  killTimeoutMs: a = 2e3
+} = {}) => {
+  let d = process.cwd(), e = null, c = () => !1;
+  const f = /* @__PURE__ */ new Set();
+  let m, w = !1;
+  const h = () => {
+    clearTimeout(m), m = setTimeout(() => {
+      if (!e || e.dead) return;
+      const n = Array.from(f);
+      f.clear(), n.length !== 0 && e.regen(n).then((o) => {
+        o.changed.length > 0 && process.stderr.write(
+          `[typefinder] regen ${o.changed.length} file(s) in ${o.duration_ms}ms
+`
+        );
+        for (const u of o.warnings)
+          process.stderr.write(`[typefinder] ${u}
+`);
+        for (const u of o.failed)
+          process.stderr.write(`[typefinder] ${u.path}: ${u.message}
+`);
+      }).catch((o) => {
+        process.stderr.write(`[typefinder] regen failed: ${o.message}
+`);
+      });
+    }, r);
+  };
+  return {
+    name: "@pentacore/vite-plugin-laravel-typefinder",
+    enforce: "pre",
+    configResolved(n) {
+      d = n.root, w = n.command === "build";
+    },
+    async configureServer(n) {
+      var u;
+      if (w) return;
+      e = await y.spawn({
+        command: l,
+        cwd: d,
+        startupTimeoutMs: i,
+        killTimeoutMs: a
+      });
+      const o = t ?? B(e.handshake.categories);
+      c = k(o), e.on("died", (g) => {
+        process.stderr.write(
+          `[typefinder] watcher exited: ${g} — restart the dev server
+`
+        );
+      }), n.ws.on("typefinder:full-regen", () => {
+        e && !e.dead && e.regen([]).catch((g) => {
+          process.stderr.write(`[typefinder] full regen failed: ${g.message}
+`);
+        });
+      }), (u = n.httpServer) == null || u.once("close", () => void (e == null ? void 0 : e.kill())), process.once("exit", () => void (e == null ? void 0 : e.kill()));
+    },
+    async buildStart() {
+      if (w) {
+        if (s === !1) {
+          process.stderr.write(`[typefinder] build-time generation disabled
+`);
+          return;
+        }
+        try {
+          await M(s, { cwd: d });
+        } catch (n) {
+          const o = n instanceof Error ? n.message : String(n);
+          throw new Error(`[typefinder] build-time generation failed: ${o}`, { cause: n });
+        }
+        return;
+      }
+      if (e && !e.dead) {
+        const n = await e.regen([]);
+        n.changed.length > 0 && process.stderr.write(
+          `[typefinder] initial regen: ${n.changed.length} file(s) in ${n.duration_ms}ms
+`
+        );
+      }
+    },
+    handleHotUpdate({ file: n }) {
+      w || !e || e.dead || c(n) && (f.add(n), h());
+    },
+    async closeBundle() {
+      e && !e.dead && await e.kill();
+    }
+  };
+}, B = (l) => {
+  const s = [];
+  for (const t of Object.keys(l)) {
+    const r = l[t];
+    r.enabled && s.push(...r.paths);
+  }
+  return s;
+};
+export {
+  G as default,
+  G as typefinder
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pentacore/vite-plugin-laravel-typefinder",
-    "version": "4.0.2",
+    "version": "4.2.0",
     "description": "Vite plugin for Laravel Typefinder — auto-generate TypeScript types from Models, Enums, Casts, and Requests.",
     "keywords": [
         "vite",
@@ -17,29 +17,36 @@
     },
     "type": "module",
     "scripts": {
-        "build": "unbuild",
-        "dev": "unbuild --stub",
+        "build": "vite build",
+        "dev": "vite build --watch",
         "lint": "eslint src/",
-        "lint:fix": "eslint src/ --fix"
+        "lint:fix": "eslint src/ --fix",
+        "test": "vitest run",
+        "test:watch": "vitest"
     },
-    "module": "dist/index.mjs",
-    "types": "dist/index.d.mts",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
     "exports": {
         ".": {
-            "import": "./dist/index.mjs",
-            "types": "./dist/index.d.mts"
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
         }
     },
+    "dependencies": {
+        "picomatch": "^4.0.4"
+    },
     "devDependencies": {
-        "@types/node": "^22.15.17",
-        "eslint": "^9.0.0",
-        "@eslint/js": "^9.0.0",
-        "typescript-eslint": "^8.0.0",
-        "minimatch": "^10.0.1",
-        "rollup": "^4.40.2",
-        "typescript": "^5.8.0",
-        "unbuild": "^3.5.0",
-        "vite": "^6.3.5"
+        "@codecov/vite-plugin": "^2.0.1",
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^24.12.2",
+        "@types/picomatch": "^4.0.3",
+        "@vitest/coverage-v8": "^4.1.4",
+        "eslint": "^10.2.0",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.58.2",
+        "vite": "^6.4.2",
+        "vite-plugin-dts": "^4.5.4",
+        "vitest": "^4.1.4"
     },
     "files": [
         "dist"

package/dist/index.d.mts

@@ -1,77 +0,0 @@
-import { Plugin } from 'vite';
-
-/**
- * Options for the `typefinder` Vite plugin.
- *
- * All fields are optional — the defaults work for a standard Laravel project
- * running PHP directly. Override `command` when using Sail, Herd, Docker, or
- * any other PHP runtime wrapper. Extend `watch` when you use Typefinder's
- * resource / page / broadcast features so the plugin regenerates on those
- * file changes too.
- */
-interface TypefinderOptions {
-    /**
-     * Glob patterns (relative to the Vite project root) whose changes should
-     * trigger a regeneration. Matched against each HMR update's file path.
-     *
-     * The default covers models, enums, and form requests — the always-on
-     * Typefinder categories. If you enable optional categories (Inertia pages,
-     * broadcasting) or use JSON resources, extend the list so updates on
-     * those directories also re-run the generator.
-     *
-     * @default ['app/Models/** /*.php', 'app/Enums/** /*.php', 'app/Http/Requests/** /*.php']
-     */
-    watch?: string[];
-    /**
-     * Shell command used to regenerate types. Customize for non-standard
-     * PHP runtimes:
-     *
-     * - Sail: `'./vendor/bin/sail artisan typefinder:generate'`
-     * - Herd: `'herd php artisan typefinder:generate'`
-     * - Docker: `'docker compose exec app php artisan typefinder:generate'`
-     *
-     * @default 'php artisan typefinder:generate'
-     */
-    command?: string;
-    /**
-     * Debounce window in milliseconds. When multiple files change within this
-     * window the plugin coalesces them into a single regeneration. Keep small
-     * for fast feedback; raise if your editor triggers noisy saves.
-     *
-     * @default 100
-     */
-    debounceMs?: number;
-}
-/**
- * Vite plugin that runs `php artisan typefinder:generate` automatically —
- * once at `buildStart`, and again on every HMR update whose file path
- * matches any pattern in {@link TypefinderOptions.watch}.
- *
- * Install the Composer package `pentacore/laravel-typefinder` in your Laravel
- * app, then register this plugin in `vite.config.ts`:
- *
- * ```ts
- * import { defineConfig } from 'vite';
- * import laravel from 'laravel-vite-plugin';
- * import typefinder from '@pentacore/vite-plugin-laravel-typefinder';
- *
- * export default defineConfig({
- *   plugins: [
- *     laravel({ input: ['resources/js/app.ts'] }),
- *     typefinder(),
- *   ],
- * });
- * ```
- *
- * Regenerations are debounced and serialized — concurrent triggers coalesce
- * into at most one in-flight run plus one queued run. The plugin uses Vite's
- * `enforce: 'pre'` ordering so types are fresh before other plugins inspect
- * them.
- *
- * @param options Plugin options. See {@link TypefinderOptions}.
- * @returns A Vite plugin.
- */
-declare const typefinder: ({ watch, command, debounceMs, }?: TypefinderOptions) => Plugin;
-
-export { typefinder as default, typefinder };
-export type { TypefinderOptions };