@d1g1tal/tsnode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 D1g1talEntr0py
+
+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,67 @@
+# tsnode
+
+`tsnode` is a CLI-first TypeScript runner for modern Node.js. It registers synchronous loader hooks and runs local `.ts` entrypoints directly, without requiring loader flags at invocation time.
+
+## Status
+
+This package currently supports the `tsnode` CLI as its public interface. The loader hook implementation is not yet a documented import API.
+
+## Requirements
+
+- Node.js `>=22.15.0`
+
+## Install
+
+```bash
+pnpm add -D tsnode
+```
+
+You can also install it globally:
+
+```bash
+pnpm add -g tsnode
+```
+
+## Usage
+
+Run a TypeScript entrypoint directly:
+
+```bash
+tsnode ./src/index.ts
+```
+
+Arguments after the entry file are passed through to the loaded program:
+
+```bash
+tsnode ./scripts/build.ts --watch
+```
+
+## What It Resolves
+
+The loader supports these local resolution patterns:
+
+- Relative imports such as `./helper.js` resolving to `./helper.ts`
+- Relative paths without an extension resolving to `.ts`
+- Directory imports resolving to `index.ts`
+- `src/` aliases resolving from the nearest project root containing `tsconfig.json` or `package.json`
+
+## Cache Behavior
+
+- Transpiled output is cached under `~/.cache/tsnode/<typescript-version>`
+- Cache keys include the source path, file metadata, current Node version, and TypeScript version
+- Cache writes are asynchronous so a cold compile does not block repeated loads in the same process
+
+## Known Limitations
+
+- The package is currently CLI-first; importing loader hooks directly is not yet a supported API
+- The transpiler targets modern ESM output for Node.js rather than older runtimes
+- Stage 3 decorators are downleveled during transpilation because current Node.js releases still do not execute that syntax directly
+
+## Development
+
+```bash
+pnpm run build
+pnpm run test
+pnpm run type-check
+pnpm run release:check
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { registerHooks } from 'node:module';
+import { resolve as resolvePath } from 'node:path';
+import { loaderLifecycle, load, resolve } from './hooks.js';
+// Use top-level await to ensure the loader is registered before importing the target.
+await using _loader = loaderLifecycle;
+// Register the TypeScript loader hooks synchronously before importing the target.
+registerHooks({ load, resolve });
+const entry = process.argv[2];
+if (entry === undefined) {
+    process.stderr.write('Usage: tsnode <file.ts> [...args]\n');
+    process.exit(1);
+}
+// Shift argv so the target file looks like the main script to the loaded module.
+process.argv.splice(1, 1);
+await import(entry.startsWith('file:') ? entry : pathToFileURL(resolvePath(entry)).href);

package/dist/hooks.d.ts

@@ -0,0 +1,8 @@
+import type { ResolveHookSync, LoadHookSync } from 'node:module';
+export declare const loaderLifecycle: {
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export declare const resolve: ResolveHookSync;
+export declare const load: LoadHookSync;
+export declare function disposeLoader(): Promise<void>;

package/dist/hooks.js

@@ -0,0 +1,217 @@
+import process from 'node:process';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { mkdirSync, readFileSync, statSync } from 'node:fs';
+import { rename, rm, writeFile } from 'node:fs/promises';
+import { transpileModule, ScriptTarget, ModuleKind, version as typescriptVersion } from 'typescript';
+const cacheDir = resolvePath(homedir(), '.cache', 'tsnode', typescriptVersion);
+mkdirSync(cacheDir, { recursive: true });
+const transpileTarget = ScriptTarget.ES2022;
+const loaderCacheVersion = 'target-es2022';
+const cachedEntries = new Set();
+const cacheVersion = `${process.versions.node}-${typescriptVersion}-${loaderCacheVersion}`;
+const resolveCache = new Map();
+const statCache = new Map();
+const pathHashCache = new Map();
+const projectRootCache = new Map();
+const pendingCacheWrites = new Map();
+let cacheWriteSequence = 0;
+function clearLoaderCaches() {
+    cachedEntries.clear();
+    resolveCache.clear();
+    statCache.clear();
+    pathHashCache.clear();
+    projectRootCache.clear();
+}
+async function flushPendingCacheWrites() {
+    const writes = [...pendingCacheWrites.values()];
+    if (writes.length === 0) {
+        return;
+    }
+    await Promise.allSettled(writes);
+}
+export const loaderLifecycle = {
+    [Symbol.dispose]() {
+        clearLoaderCaches();
+    },
+    async [Symbol.asyncDispose]() {
+        await flushPendingCacheWrites();
+        clearLoaderCaches();
+    }
+};
+function hashPath(path) {
+    const cached = pathHashCache.get(path);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const hash = createHash('sha256').update(path).digest('hex').slice(0, 16);
+    pathHashCache.set(path, hash);
+    return hash;
+}
+function getStat(path) {
+    const cached = statCache.get(path);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const stat = statSync(path, { throwIfNoEntry: false });
+    if (stat === undefined || !stat.isFile()) {
+        return undefined;
+    }
+    const info = { mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ino: stat.ino, size: stat.size };
+    statCache.set(path, info);
+    return info;
+}
+function fileExists(path) {
+    return getStat(path) !== undefined;
+}
+function scheduleCacheWrite(cacheFileName, cachePath, source) {
+    if (cachedEntries.has(cacheFileName) || pendingCacheWrites.has(cacheFileName)) {
+        return;
+    }
+    const temporaryCachePath = cachePath + '.' + process.pid + '.' + cacheWriteSequence++ + '.tmp';
+    const writePromise = writeFile(temporaryCachePath, source)
+        .then(() => rename(temporaryCachePath, cachePath))
+        .then(() => {
+        cachedEntries.add(cacheFileName);
+    })
+        .catch(error => {
+        rm(temporaryCachePath, { force: true }).catch(() => undefined);
+        process.stderr.write('[tsnode] cache write failed: ' + String(error) + '\n');
+    })
+        .finally(() => {
+        pendingCacheWrites.delete(cacheFileName);
+    });
+    pendingCacheWrites.set(cacheFileName, writePromise);
+}
+function directoryExists(path) {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    return stat !== undefined && stat.isDirectory();
+}
+function readCachedSource(cacheFileName, cachePath) {
+    try {
+        const source = readFileSync(cachePath, 'utf8');
+        cachedEntries.add(cacheFileName);
+        return source;
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : undefined;
+        cachedEntries.delete(cacheFileName);
+        if (code !== 'ENOENT') {
+            process.stderr.write('[tsnode] cache read failed: ' + String(error) + '\n');
+        }
+        return undefined;
+    }
+}
+function findProjectRoot(startDirectory) {
+    const cached = projectRootCache.get(startDirectory);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let currentDirectory = startDirectory;
+    for (;;) {
+        if (fileExists(resolvePath(currentDirectory, 'tsconfig.json')) || fileExists(resolvePath(currentDirectory, 'package.json'))) {
+            projectRootCache.set(startDirectory, currentDirectory);
+            return currentDirectory;
+        }
+        const parentDirectory = dirname(currentDirectory);
+        if (parentDirectory === currentDirectory) {
+            const fallbackDirectory = process.cwd();
+            projectRootCache.set(startDirectory, fallbackDirectory);
+            return fallbackDirectory;
+        }
+        currentDirectory = parentDirectory;
+    }
+}
+function resolveSrcRoot(parentURL) {
+    if (parentURL !== undefined && parentURL.startsWith('file:')) {
+        const parentDirectory = dirname(fileURLToPath(parentURL));
+        const projectRoot = findProjectRoot(parentDirectory);
+        const candidateSrcRoot = resolvePath(projectRoot, 'src');
+        if (directoryExists(candidateSrcRoot)) {
+            return candidateSrcRoot;
+        }
+    }
+    return resolvePath(process.cwd(), 'src');
+}
+function resolveTsPath(absPath) {
+    if (absPath.endsWith('.ts') && fileExists(absPath)) {
+        return absPath;
+    }
+    if (absPath.endsWith('.js')) {
+        const tsPath = absPath.slice(0, -3) + '.ts';
+        if (fileExists(tsPath)) {
+            return tsPath;
+        }
+    }
+    const withTs = absPath + '.ts';
+    if (fileExists(withTs)) {
+        return withTs;
+    }
+    const indexTs = absPath + '/index.ts';
+    return fileExists(indexTs) ? indexTs : null;
+}
+export const resolve = function (specifier, context, nextResolve) {
+    const firstChar = specifier.charCodeAt(0);
+    const isRelative = firstChar === 46 /* . */;
+    const isSrcAlias = firstChar === 115 /* s */ && specifier.startsWith('src/');
+    if (!isRelative && !isSrcAlias) {
+        return nextResolve(specifier, context);
+    }
+    const cacheKey = context.parentURL !== undefined ? specifier + '\0' + context.parentURL : specifier;
+    const cached = resolveCache.get(cacheKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let absPath = null;
+    if (isSrcAlias) {
+        absPath = resolvePath(resolveSrcRoot(context.parentURL), specifier.slice(4));
+    }
+    else if (context.parentURL !== undefined && context.parentURL.startsWith('file:')) {
+        absPath = resolvePath(dirname(fileURLToPath(context.parentURL)), specifier);
+    }
+    if (absPath !== null) {
+        const tsPath = resolveTsPath(absPath);
+        if (tsPath !== null) {
+            const result = { url: pathToFileURL(tsPath).href, format: 'module', shortCircuit: true };
+            resolveCache.set(cacheKey, result);
+            return result;
+        }
+    }
+    return nextResolve(specifier, context);
+};
+export const load = function (url, context, nextLoad) {
+    if (!url.startsWith('file:') || !url.endsWith('.ts')) {
+        return nextLoad(url, context);
+    }
+    const path = fileURLToPath(url);
+    const info = getStat(path);
+    if (info === undefined) {
+        return nextLoad(url, context);
+    }
+    const cacheFileName = hashPath(path) + '-' + info.mtimeMs + '-' + info.ctimeMs + '-' + info.ino + '-' + info.size + '-' + cacheVersion + '.js';
+    const cachePath = resolvePath(cacheDir, cacheFileName);
+    let source = readCachedSource(cacheFileName, cachePath);
+    if (source === undefined) {
+        const sourceCode = readFileSync(path, 'utf8');
+        const result = transpileModule(sourceCode, {
+            compilerOptions: {
+                // Downlevel stage 3 decorators because current Node still can't execute
+                // the syntax directly even though TypeScript can parse and type-check it.
+                target: transpileTarget,
+                module: ModuleKind.ESNext,
+                jsx: undefined,
+                declaration: false,
+                sourceMap: false
+            },
+            reportDiagnostics: true
+        });
+        source = result.outputText;
+        scheduleCacheWrite(cacheFileName, cachePath, source);
+    }
+    return { format: 'module', source, shortCircuit: true };
+};
+export async function disposeLoader() {
+    await loaderLifecycle[Symbol.asyncDispose]();
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@d1g1tal/tsnode",
+	"author": "D1g1talEntr0py",
+  "version": "0.1.0",
+	"license": "MIT",
+  "description": "Zero-flag Node.js TypeScript loader — run .ts files directly with `tsnode foo.ts`.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/D1g1talEntr0py/tsnode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/D1g1talEntr0py/tsnode/issues"
+  },
+  "maintainers": [
+    {
+      "name": "D1g1talEntr0py",
+      "email": "jason.dimeo@gmail.com"
+    }
+  ],
+  "engines": {
+    "node": ">=22.15.0"
+  },
+	"packageManager": "pnpm@11.8.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+			"types": "./dist/hooks.d.ts",
+			"default": "./dist/hooks.js"
+		}
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "tsnode": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"import('node:fs').then(({chmodSync})=>chmodSync('./dist/cli.js',0o755))\"",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm run clean && pnpm run build",
+    "release:check": "pnpm run clean && pnpm run build && pnpm run test && pnpm run type-check && npm pack --dry-run",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "vitest": "^4.1.8"
+  },
+
+	"keywords": [
+    "typescript",
+    "node",
+    "loader",
+    "esm",
+    "cli",
+    "transpile"
+  ]
+}