@alexaegis/turbowatch 0.7.0

package/index.cjs

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const common = require("@alexaegis/common");
+const workspaceTools = require("@alexaegis/workspace-tools");
+const node_child_process = require("node:child_process");
+const node_path = require("node:path");
+const fs = require("@alexaegis/fs");
+const normalizeTurbowatchLocalNodeModulesOptions = (options) => {
+  return {
+    ...fs.normalizeCwdOption(options),
+    deep: options?.deep ?? true,
+    useGitIgnore: options?.useGitIgnore ?? false,
+    logChangedFiles: options?.logChangedFiles ?? false,
+    buildDependenciesScript: options?.buildDependenciesScript ?? "build:dependencies",
+    packageManagerCommand: options?.packageManagerCommand ?? "pnpm",
+    onFirstBuild: options?.onFirstBuild,
+    devScript: options?.devScript ?? "dev_"
+  };
+};
+const turbowatchLocalNodeModules = async (rawOptions) => {
+  const options = normalizeTurbowatchLocalNodeModulesOptions(rawOptions);
+  console.log("turbowatch started in", options.cwd);
+  const currentPackagePath = workspaceTools.getCurrentPackageRoot(options.cwd);
+  if (!currentPackagePath) {
+    throw new Error("Not in a package!");
+  }
+  const currentPackagesNodeModulesPath = node_path.join(currentPackagePath, workspaceTools.NODE_MODULES_DIRECTORY_NAME);
+  const workspacePackages = await workspaceTools.collectWorkspacePackages({
+    ...options,
+    skipWorkspaceRoot: true
+  });
+  const doNotMatchPackageJson = ["not", ["match", "package.json", "basename"]];
+  const matchInLocalPackageDirectories = [
+    "anyof",
+    ...workspacePackages.map((workspacePackage) => workspacePackage.packageJson.name).filter(common.isNotNullish).map((packageName) => ["dirname", packageName])
+  ];
+  const commonIgnoredDirs = [
+    ["dirname", "dist"],
+    ["dirname", ".turbo"],
+    ["dirname", ".vercel"],
+    ["dirname", ".cache"],
+    ["dirname", "coverage"],
+    ["dirname", "build"],
+    ["match", "vite(st)?.config.*"]
+  ];
+  if (!options.deep) {
+    commonIgnoredDirs.push(["dirname", "node_modules"]);
+  }
+  const doNotMatchCommonOutputs = ["not", ["anyof", ...commonIgnoredDirs]];
+  const watchExpression = [
+    "allof",
+    matchInLocalPackageDirectories,
+    doNotMatchCommonOutputs,
+    doNotMatchPackageJson
+  ];
+  if (options.useGitIgnore) {
+    let ignoreEntries = await workspaceTools.collectIgnoreEntries(options);
+    if (options.deep) {
+      ignoreEntries = ignoreEntries.filter(
+        (entry) => !entry.includes(workspaceTools.NODE_MODULES_DIRECTORY_NAME)
+      );
+    }
+    const ignoreMatchEntries = ignoreEntries.map((ignoreEntry) => [
+      "match",
+      ignoreEntry
+    ]);
+    const doNotMatchIgnored = ["not", ["anyof", ...ignoreMatchEntries]];
+    watchExpression.push(doNotMatchIgnored);
+  }
+  let changeCount = 0;
+  const startCommand = () => {
+    return node_child_process.spawn(options.packageManagerCommand, ["run", options.devScript], {
+      stdio: "inherit"
+    });
+  };
+  let spawnedOnFirstBuild;
+  return {
+    project: currentPackagesNodeModulesPath,
+    debounce: { wait: 50 },
+    triggers: [
+      {
+        expression: watchExpression,
+        name: "build",
+        retry: { retries: 0 },
+        onChange: async ({ spawn: spawn2, files }) => {
+          if (options.logChangedFiles) {
+            console.log("changed files:", files);
+          }
+          await spawn2`${options.packageManagerCommand} run ${options.buildDependenciesScript}`;
+          if (changeCount < 1) {
+            spawnedOnFirstBuild = options.onFirstBuild ? options.onFirstBuild() : startCommand();
+          }
+          changeCount++;
+        },
+        onTeardown: async () => {
+          if (spawnedOnFirstBuild) {
+            spawnedOnFirstBuild.kill();
+          }
+          await common.noopAsync();
+        }
+      }
+    ]
+  };
+};
+exports.normalizeTurbowatchLocalNodeModulesOptions = normalizeTurbowatchLocalNodeModulesOptions;
+exports.turbowatchLocalNodeModules = turbowatchLocalNodeModules;

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from './internal/watch-local-node-modules.js';
+export * from './internal/watch-local-node-modules.options.js';

package/index.js

@@ -0,0 +1,106 @@
+import { isNotNullish, noopAsync } from "@alexaegis/common";
+import { getCurrentPackageRoot, NODE_MODULES_DIRECTORY_NAME, collectWorkspacePackages, collectIgnoreEntries } from "@alexaegis/workspace-tools";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { normalizeCwdOption } from "@alexaegis/fs";
+const normalizeTurbowatchLocalNodeModulesOptions = (options) => {
+  return {
+    ...normalizeCwdOption(options),
+    deep: options?.deep ?? true,
+    useGitIgnore: options?.useGitIgnore ?? false,
+    logChangedFiles: options?.logChangedFiles ?? false,
+    buildDependenciesScript: options?.buildDependenciesScript ?? "build:dependencies",
+    packageManagerCommand: options?.packageManagerCommand ?? "pnpm",
+    onFirstBuild: options?.onFirstBuild,
+    devScript: options?.devScript ?? "dev_"
+  };
+};
+const turbowatchLocalNodeModules = async (rawOptions) => {
+  const options = normalizeTurbowatchLocalNodeModulesOptions(rawOptions);
+  console.log("turbowatch started in", options.cwd);
+  const currentPackagePath = getCurrentPackageRoot(options.cwd);
+  if (!currentPackagePath) {
+    throw new Error("Not in a package!");
+  }
+  const currentPackagesNodeModulesPath = join(currentPackagePath, NODE_MODULES_DIRECTORY_NAME);
+  const workspacePackages = await collectWorkspacePackages({
+    ...options,
+    skipWorkspaceRoot: true
+  });
+  const doNotMatchPackageJson = ["not", ["match", "package.json", "basename"]];
+  const matchInLocalPackageDirectories = [
+    "anyof",
+    ...workspacePackages.map((workspacePackage) => workspacePackage.packageJson.name).filter(isNotNullish).map((packageName) => ["dirname", packageName])
+  ];
+  const commonIgnoredDirs = [
+    ["dirname", "dist"],
+    ["dirname", ".turbo"],
+    ["dirname", ".vercel"],
+    ["dirname", ".cache"],
+    ["dirname", "coverage"],
+    ["dirname", "build"],
+    ["match", "vite(st)?.config.*"]
+  ];
+  if (!options.deep) {
+    commonIgnoredDirs.push(["dirname", "node_modules"]);
+  }
+  const doNotMatchCommonOutputs = ["not", ["anyof", ...commonIgnoredDirs]];
+  const watchExpression = [
+    "allof",
+    matchInLocalPackageDirectories,
+    doNotMatchCommonOutputs,
+    doNotMatchPackageJson
+  ];
+  if (options.useGitIgnore) {
+    let ignoreEntries = await collectIgnoreEntries(options);
+    if (options.deep) {
+      ignoreEntries = ignoreEntries.filter(
+        (entry) => !entry.includes(NODE_MODULES_DIRECTORY_NAME)
+      );
+    }
+    const ignoreMatchEntries = ignoreEntries.map((ignoreEntry) => [
+      "match",
+      ignoreEntry
+    ]);
+    const doNotMatchIgnored = ["not", ["anyof", ...ignoreMatchEntries]];
+    watchExpression.push(doNotMatchIgnored);
+  }
+  let changeCount = 0;
+  const startCommand = () => {
+    return spawn(options.packageManagerCommand, ["run", options.devScript], {
+      stdio: "inherit"
+    });
+  };
+  let spawnedOnFirstBuild;
+  return {
+    project: currentPackagesNodeModulesPath,
+    debounce: { wait: 50 },
+    triggers: [
+      {
+        expression: watchExpression,
+        name: "build",
+        retry: { retries: 0 },
+        onChange: async ({ spawn: spawn2, files }) => {
+          if (options.logChangedFiles) {
+            console.log("changed files:", files);
+          }
+          await spawn2`${options.packageManagerCommand} run ${options.buildDependenciesScript}`;
+          if (changeCount < 1) {
+            spawnedOnFirstBuild = options.onFirstBuild ? options.onFirstBuild() : startCommand();
+          }
+          changeCount++;
+        },
+        onTeardown: async () => {
+          if (spawnedOnFirstBuild) {
+            spawnedOnFirstBuild.kill();
+          }
+          await noopAsync();
+        }
+      }
+    ]
+  };
+};
+export {
+  normalizeTurbowatchLocalNodeModulesOptions,
+  turbowatchLocalNodeModules
+};

package/index.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.spec.d.ts.map

package/index.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.spec.d.ts","sourceRoot":"","sources":["../src/index.spec.ts"],"names":[],"mappings":""}

package/internal/watch-local-node-modules.d.ts

@@ -0,0 +1,5 @@
+import { type TurbowatchLocalNodeModulesOptions } from './watch-local-node-modules.options.js';
+/**
+ * how about relying on CWD, and do the whole thing from a package?
+ */
+export declare const turbowatchLocalNodeModules: (rawOptions?: TurbowatchLocalNodeModulesOptions) => Promise<Parameters<typeof import('turbowatch').watch>[0]>;

package/internal/watch-local-node-modules.options.d.ts

@@ -0,0 +1,69 @@
+/// <reference types="node" resolution-mode="require"/>
+import type { Defined } from '@alexaegis/common';
+import { type CwdOption } from '@alexaegis/fs';
+import type { ChildProcess } from 'node:child_process';
+export interface TurbowatchLocalNodeModulesOptions extends CwdOption {
+    /**
+     * If true, it will make sure ignore statements do not contain node_modules
+     * so the watcher can watch the entire dependency tree.
+     *
+     * If false deeper node_modules will be ignored.
+     *
+     * @default true
+     */
+    deep?: boolean | undefined;
+    /**
+     * If the default ignored files like
+     * - 'dist'
+     * - '.turbo'
+     * - '.vercel'
+     * - '.cache'
+     * - 'coverage'
+     * - 'build'
+     *
+     * Does not suffice, you can enable this and then it will read all the
+     * .gitignore files up your project root and include those too in the do
+     * not watch list. This could potentially ignore more than you actually
+     * want though!
+     *
+     * @default false
+     */
+    useGitIgnore?: boolean | undefined;
+    /**
+     * Log out changed files on every change. Useful for debugging if you
+     * notice builds are getting triggered over and over again.
+     *
+     * @default false
+     */
+    logChangedFiles?: boolean | undefined;
+    /**
+     * The command used to build the dependencies of this package.
+     *
+     * @default 'build:dependencies'
+     */
+    buildDependenciesScript?: string | undefined;
+    /**
+     * Which package manager to invoke when running buildDependenciesScript
+     *
+     * @default 'pnpm'
+     */
+    packageManagerCommand?: string | undefined;
+    /**
+     * Called the first time buildDependenciesScript finished
+     * You can use this to start your app if the way devScript doesn't suffice.
+     * If this is defined, devScript will not be used!
+     *
+     * It can be async but it won't be awaited!
+     */
+    onFirstBuild?: (() => ChildProcess | undefined) | undefined;
+    /**
+     * What package.json script should be started once buildDependenciesScript
+     * is first finished. By default it's `dev_` with an underscore at the
+     * end as this turbowatch call should be named `dev`
+     *
+     * @default 'dev_'
+     */
+    devScript?: string | undefined;
+}
+export type NormalizedTurbowatchLocalNodeModulesOptions = Defined<Omit<TurbowatchLocalNodeModulesOptions, 'onFirstBuild'>> & Pick<TurbowatchLocalNodeModulesOptions, 'onFirstBuild'>;
+export declare const normalizeTurbowatchLocalNodeModulesOptions: (options?: TurbowatchLocalNodeModulesOptions) => NormalizedTurbowatchLocalNodeModulesOptions;

package/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Győri Sándor
+
+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/local-node-modules.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const index = require("./index.cjs");
+require("@alexaegis/common");
+require("@alexaegis/workspace-tools");
+require("node:child_process");
+require("node:path");
+require("@alexaegis/fs");
+exports.turbowatchLocalNodeModules = index.turbowatchLocalNodeModules;

package/local-node-modules.d.ts

@@ -0,0 +1 @@
+export * from './internal/watch-local-node-modules.js';

package/local-node-modules.js

@@ -0,0 +1,9 @@
+import { turbowatchLocalNodeModules } from "./index.js";
+import "@alexaegis/common";
+import "@alexaegis/workspace-tools";
+import "node:child_process";
+import "node:path";
+import "@alexaegis/fs";
+export {
+  turbowatchLocalNodeModules
+};

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@alexaegis/turbowatch",
+  "description": "A turbowatch configuration to watch local dependencies through node_modules",
+  "version": "0.7.0",
+  "license": "MIT",
+  "private": false,
+  "archetype": {
+    "platform": "node",
+    "language": "ts",
+    "kind": "lib"
+  },
+  "keywords": [
+    "managed-by-autotool",
+    "turbowatch"
+  ],
+  "author": {
+    "email": "alexaegis@gmail.com",
+    "name": "Alex Aegis",
+    "url": "https://github.com/AlexAegis"
+  },
+  "homepage": "https://github.com/AlexAegis/js-tooling",
+  "repository": {
+    "url": "git+https://github.com/AlexAegis/js-tooling",
+    "type": "git",
+    "directory": "packages/turbowatch"
+  },
+  "bugs": {
+    "email": "alexaegis@gmail.com",
+    "url": "https://github.com/AlexAegis/js-tooling/issues"
+  },
+  "type": "module",
+  "config": {
+    "engine-strict": true
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.10.0",
+    "pnpm": ">=8.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "default": "./index.js"
+    },
+    "./local-node-modules": {
+      "types": "./local-node-modules.d.ts",
+      "import": "./local-node-modules.js",
+      "require": "./local-node-modules.cjs",
+      "default": "./local-node-modules.js"
+    },
+    "./readme": "./readme.md"
+  },
+  "dependencies": {
+    "@alexaegis/common": "^0.6.1",
+    "@alexaegis/fs": "^0.6.1",
+    "@alexaegis/workspace-tools": "^0.6.1"
+  },
+  "devDependencies": {
+    "@alexaegis/eslint-config-vitest": "^0.7.0",
+    "@alexaegis/ts": "^0.7.0",
+    "@alexaegis/vite": "^0.7.0",
+    "@alexaegis/vitest": "^0.7.0",
+    "@types/node": "^20.4.6",
+    "publint": "^0.2.0",
+    "turbowatch": "^2.29.4",
+    "typescript": "^5.1.6",
+    "vite": "^4.4.8",
+    "vitest": "^0.34.1"
+  },
+  "scripts": {
+    "build": "turbo run build-lib_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "build-lib_": "vite build",
+    "lint:depcheck": "turbo run lint:depcheck_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "lint:depcheck_": "depcheck",
+    "lint:es": "turbo run lint:es_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "lint:es_": "eslint --max-warnings=0 --fix --no-error-on-unmatched-pattern .",
+    "lint:format": "turbo run lint:format_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "lint:format_": "prettier --cache-location .cache/prettier --plugin prettier-plugin-svelte --plugin prettier-plugin-tailwindcss --check .",
+    "lint:md": "turbo run lint:md_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "lint:md_": "remark --frail --no-stdout --silently-ignore .",
+    "lint:tsc": "turbo run lint:tsc_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "lint:tsc_": "tsc --noEmit",
+    "publint": "BUILD_REASON='publish' turbo run publint_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "publint_": "publint dist",
+    "all": "BUILD_REASON='publish' turbo run all_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "format": "turbo run format_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "format_": "prettier --cache-location .cache/prettier --plugin prettier-plugin-svelte --plugin prettier-plugin-tailwindcss --write .",
+    "test": "turbo run test_ --concurrency 16 --cache-dir .cache/turbo --filter @alexaegis/turbowatch",
+    "test_": "vitest --passWithNoTests --coverage --run",
+    "test:watch": "vitest --passWithNoTests --coverage"
+  }
+}

package/readme.md

@@ -0,0 +1,97 @@
+# [@alexaegis/turbowatch](https://github.com/AlexAegis/js-tooling/tree/master/packages/turbowatch)
+
+[![npm](https://img.shields.io/npm/v/@alexaegis/turbowatch/latest)](https://www.npmjs.com/package/@alexaegis/turbowatch)
+[![ci](https://github.com/AlexAegis/js-tooling/actions/workflows/cicd.yml/badge.svg)](https://github.com/AlexAegis/js-tooling/actions/workflows/cicd.yml)
+[![codacy](https://app.codacy.com/project/badge/Grade/7939332dc9454dc1b0529e720ff902e6)](https://www.codacy.com/gh/AlexAegis/js-tooling/dashboard?utm_source=github.com&utm_medium=referral&utm_content=AlexAegis/js-tooling&utm_campaign=Badge_Grade)
+
+Holds a configuration for [`turbowatch`](https://github.com/gajus/turbowatch) to
+watch local dependencies changing through `node_modules`.
+
+It will first run `buildDependenciesScript`, then after that's finished the
+first time, it will run `devScript`.
+
+## Turbowatch configuration example
+
+> `apps/my-app/dev.js`
+
+```js
+import { turbowatchLocalNodeModules } from '@alexaegis/turbowatch';
+import { watch } from 'turbowatch';
+
+void (async () => {
+  await watch(
+    await turbowatchLocalNodeModules({
+      buildDependenciesScript: 'build:dependencies',
+      devScript: 'dev_',
+    }),
+  );
+})();
+```
+
+> It's using an IIFE because turbowatch does not understand top-level awaits
+
+## Turbo example
+
+When using with turbo, it's important that `turbo` cannot invoke itself. (In
+older versions of turbo it was allowed but worked wonky, since then it's
+actively prohibited) So when starting your app, start the invokation from
+`turbowatch`
+
+> `apps/my-app/package.json`
+
+```json
+{
+  "scripts": {
+    "build:dependencies": "turbo run build-lib_ --filter my-app",
+    "dev": "turbowatch dev.js",
+    "dev_": "vite"
+  }
+}
+```
+
+And then the interesting part of a `turbo.json`. For the `turbowatch` setup
+specifically, only the `build-lib_` task is used. Since `turbowatch` through the
+`"build:dependencies"` npm script already takes care of building the
+dependencies of the app, there's no need to start the app through `turbo`. For a
+more comprehensive `turbo.json` file, check the one in this package's
+repository.
+
+> `turbo.json`
+
+```json
+{
+  "$schema": "https://turborepo.org/schema.json",
+  "pipeline": {
+    "build-app_": {
+      "dependsOn": ["^build-lib_"],
+      "outputs": ["dist/**"]
+    },
+    "build-lib_": {
+      "dependsOn": ["^build-lib_"],
+      "outputs": ["dist/**"]
+    },
+    "dev_": {
+      "cache": false,
+      "dependsOn": ["^build-lib_"],
+      "persistent": true
+    }
+  }
+}
+```
+
+> I'm using separate build tasks for apps and libs, so I can skip building the
+> app when I'm running `turbo run build-lib_ --filter my-app`, if they'd use the
+> same script, the app would get built every time a dependency changes.
+
+You then start your app using the `"dev"` script. You can put one in your root
+`package.json` too, but do not forget that you can't use `turbo` for this!
+
+> `package.json`
+
+```json
+{
+  "script": {
+    "dev": "pnpm run --dir apps/my-app dev"
+  }
+}
+```