@flightdev/loader 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+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,147 @@
+# @flight-framework/loader
+
+Optional ESM loader for TypeScript extension resolution in Node.js. This package enables seamless imports without explicit file extensions.
+
+## When to Use
+
+This package is **optional**. Modern Node.js versions (22.18+) include native TypeScript support. Use this loader only if:
+
+- You are on Node.js < 22.18
+- You need custom extension resolution behavior
+- You want consistent resolution across all Node.js versions
+
+## Installation
+
+```bash
+npm install @flight-framework/loader
+```
+
+## Usage
+
+### Option 1: Node.js Native TypeScript (Recommended)
+
+Node.js v22.18+ includes native TypeScript type stripping:
+
+```bash
+# v22.18+ (enabled by default in v23.6+)
+node --experimental-strip-types ./server.ts
+
+# v25.2+ (stable, no flag needed)
+node ./server.ts
+```
+
+### Option 2: Flight Loader
+
+For older Node.js versions or custom resolution:
+
+```bash
+node --import @flight-framework/loader/register ./server.js
+```
+
+### Option 3: tsconfig.json Configuration
+
+Configure TypeScript to rewrite imports during compilation:
+
+```json
+{
+    "compilerOptions": {
+        "module": "nodenext",
+        "moduleResolution": "nodenext",
+        "rewriteRelativeImportExtensions": true,
+        "erasableSyntaxOnly": true,
+        "verbatimModuleSyntax": true
+    }
+}
+```
+
+The `rewriteRelativeImportExtensions` option (TypeScript 5.7+) rewrites `.ts` imports to `.js` in output.
+
+## How It Works
+
+The loader implements Node.js module customization hooks to:
+
+1. **Resolve** - Find files without explicit extensions by trying `.ts`, `.tsx`, `.js`, etc.
+2. **Load** - Pass TypeScript files to Node.js native type stripping (v22.18+)
+
+### Extension Priority
+
+When importing without an extension (e.g., `import { x } from './utils'`):
+
+1. `./utils.ts`
+2. `./utils.tsx`
+3. `./utils.mts`
+4. `./utils.js`
+5. `./utils.jsx`
+6. `./utils.mjs`
+7. `./utils.json`
+8. `./utils/index.ts`
+9. `./utils/index.js`
+
+## API
+
+```typescript
+import { 
+    supportsNativeTypeScript,
+    getRecommendedFlags,
+    resolveWithExtensions,
+    RESOLVE_EXTENSIONS 
+} from '@flight-framework/loader';
+
+// Check Node.js capability
+if (supportsNativeTypeScript()) {
+    // Node.js can handle TypeScript natively
+}
+
+// Get recommended CLI flags
+const flags = getRecommendedFlags();
+// ['--experimental-strip-types'] or [] for v25+
+
+// Resolve specifier with extensions
+const paths = resolveWithExtensions('./utils');
+// ['./utils.ts', './utils.tsx', './utils.mts', ...]
+```
+
+## Bundler Integration
+
+Flight's bundlers (Vite, esbuild, Rolldown) include automatic extension resolution. This loader is only needed for runtime Node.js execution outside of the bundler.
+
+### Vite
+
+```typescript
+// Automatic - resolve.extensions is configured by default
+import { defineConfig } from '@flight-framework/core';
+import { vite } from '@flight-framework/bundler-vite';
+
+export default defineConfig({
+    bundler: vite(),
+});
+```
+
+### esbuild
+
+```typescript
+// Automatic - resolveExtensions is configured by default
+import { esbuild } from '@flight-framework/bundler-esbuild';
+```
+
+### Rolldown
+
+```typescript
+// Automatic - resolve.extensions is configured by default
+import { rolldown } from '@flight-framework/bundler-rolldown';
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- For native TypeScript: Node.js >= 22.18.0
+
+## Related
+
+- [Module Resolution Guide](../../docs/module-resolution.md)
+- [RSC Boundaries](../../docs/rsc-boundaries.md)
+- [TypeScript Configuration](../../docs/typescript.md)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ESM Loader Hooks for Node.js
+ *
+ * These hooks implement the Node.js module customization API
+ * to resolve TypeScript extensions automatically.
+ *
+ * @see https://nodejs.org/api/module.html#customization-hooks
+ */
+/**
+ * Context passed to the resolve hook
+ */
+interface ResolveContext {
+    conditions: string[];
+    importAttributes: Record<string, string>;
+    parentURL?: string;
+}
+/**
+ * Result from the resolve hook
+ */
+interface ResolveResult {
+    url: string;
+    format?: 'builtin' | 'commonjs' | 'json' | 'module' | 'wasm';
+    shortCircuit?: boolean;
+}
+/**
+ * Context passed to the load hook
+ */
+interface LoadContext {
+    conditions: string[];
+    format?: string;
+    importAttributes: Record<string, string>;
+}
+/**
+ * Result from the load hook
+ */
+interface LoadResult {
+    format: 'builtin' | 'commonjs' | 'json' | 'module' | 'wasm';
+    source?: string | ArrayBuffer | SharedArrayBuffer;
+    shortCircuit?: boolean;
+}
+
+/**
+ * @flightdev/loader
+ *
+ * Optional ESM loader for TypeScript extension resolution in Node.js.
+ * This package provides automatic resolution of TypeScript file extensions
+ * for transitive imports when running in Node.js ESM mode.
+ *
+ * @example
+ * ```bash
+ * # Option 1: Use Node.js native TypeScript (v22.18+, recommended)
+ * node --experimental-strip-types ./server.ts
+ *
+ * # Option 2: Use Flight loader for older Node.js or custom resolution
+ * node --import @flightdev/loader/register ./server.js
+ * ```
+ */
+/**
+ * TypeScript file extensions that will be resolved automatically
+ */
+declare const TYPESCRIPT_EXTENSIONS: readonly [".ts", ".tsx", ".mts", ".cts"];
+/**
+ * All resolvable extensions in order of priority
+ */
+declare const RESOLVE_EXTENSIONS: readonly [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
+/**
+ * Check if Node.js version supports native TypeScript stripping
+ */
+declare function supportsNativeTypeScript(): boolean;
+/**
+ * Get recommended Node.js flags for TypeScript execution
+ */
+declare function getRecommendedFlags(): string[];
+/**
+ * Resolve a specifier with TypeScript extension fallbacks
+ */
+declare function resolveWithExtensions(specifier: string, extensions?: readonly string[]): string[];
+
+export { type LoadContext, type LoadResult, RESOLVE_EXTENSIONS, type ResolveContext, type ResolveResult, TYPESCRIPT_EXTENSIONS, getRecommendedFlags, resolveWithExtensions, supportsNativeTypeScript };

package/dist/index.js

@@ -0,0 +1,41 @@
+// src/index.ts
+var TYPESCRIPT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"];
+var RESOLVE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".json"
+];
+function supportsNativeTypeScript() {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  return major === 22 && minor >= 18 || major >= 23;
+}
+function getRecommendedFlags() {
+  if (supportsNativeTypeScript()) {
+    const [major] = process.versions.node.split(".").map(Number);
+    if (major >= 25 || major === 23 && parseInt(process.versions.node.split(".")[1]) >= 6) {
+      return [];
+    }
+    return ["--experimental-strip-types"];
+  }
+  return ["--import", "@flightdev/loader/register"];
+}
+function resolveWithExtensions(specifier, extensions = RESOLVE_EXTENSIONS) {
+  if (extensions.some((ext) => specifier.endsWith(ext))) {
+    return [specifier];
+  }
+  return extensions.map((ext) => `${specifier}${ext}`);
+}
+export {
+  RESOLVE_EXTENSIONS,
+  TYPESCRIPT_EXTENSIONS,
+  getRecommendedFlags,
+  resolveWithExtensions,
+  supportsNativeTypeScript
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\r\n * @flightdev/loader\r\n * \r\n * Optional ESM loader for TypeScript extension resolution in Node.js.\r\n * This package provides automatic resolution of TypeScript file extensions\r\n * for transitive imports when running in Node.js ESM mode.\r\n * \r\n * @example\r\n * ```bash\r\n * # Option 1: Use Node.js native TypeScript (v22.18+, recommended)\r\n * node --experimental-strip-types ./server.ts\r\n * \r\n * # Option 2: Use Flight loader for older Node.js or custom resolution\r\n * node --import @flightdev/loader/register ./server.js\r\n * ```\r\n */\r\n\r\n/**\r\n * TypeScript file extensions that will be resolved automatically\r\n */\r\nexport const TYPESCRIPT_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'] as const;\r\n\r\n/**\r\n * All resolvable extensions in order of priority\r\n */\r\nexport const RESOLVE_EXTENSIONS = [\r\n    '.ts',\r\n    '.tsx',\r\n    '.mts',\r\n    '.cts',\r\n    '.js',\r\n    '.jsx',\r\n    '.mjs',\r\n    '.cjs',\r\n    '.json',\r\n] as const;\r\n\r\n/**\r\n * Check if Node.js version supports native TypeScript stripping\r\n */\r\nexport function supportsNativeTypeScript(): boolean {\r\n    const [major, minor] = process.versions.node.split('.').map(Number);\r\n    // Node.js v22.18+ has stable type stripping (enabled by default in v23.6+)\r\n    return (major === 22 && minor >= 18) || major >= 23;\r\n}\r\n\r\n/**\r\n * Get recommended Node.js flags for TypeScript execution\r\n */\r\nexport function getRecommendedFlags(): string[] {\r\n    if (supportsNativeTypeScript()) {\r\n        const [major] = process.versions.node.split('.').map(Number);\r\n        // v23.6+ and v25.2+ have it enabled by default\r\n        if (major >= 25 || (major === 23 && parseInt(process.versions.node.split('.')[1]) >= 6)) {\r\n            return []; // No flags needed\r\n        }\r\n        return ['--experimental-strip-types'];\r\n    }\r\n    return ['--import', '@flightdev/loader/register'];\r\n}\r\n\r\n/**\r\n * Resolve a specifier with TypeScript extension fallbacks\r\n */\r\nexport function resolveWithExtensions(\r\n    specifier: string,\r\n    extensions: readonly string[] = RESOLVE_EXTENSIONS\r\n): string[] {\r\n    // If specifier already has an extension, return as-is\r\n    if (extensions.some(ext => specifier.endsWith(ext))) {\r\n        return [specifier];\r\n    }\r\n\r\n    // Generate possible paths with extensions\r\n    return extensions.map(ext => `${specifier}${ext}`);\r\n}\r\n\r\nexport type { ResolveContext, LoadContext, ResolveResult, LoadResult } from './hooks';\r\n"],"mappings":";AAoBO,IAAM,wBAAwB,CAAC,OAAO,QAAQ,QAAQ,MAAM;AAK5D,IAAM,qBAAqB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACJ;AAKO,SAAS,2BAAoC;AAChD,QAAM,CAAC,OAAO,KAAK,IAAI,QAAQ,SAAS,KAAK,MAAM,GAAG,EAAE,IAAI,MAAM;AAElE,SAAQ,UAAU,MAAM,SAAS,MAAO,SAAS;AACrD;AAKO,SAAS,sBAAgC;AAC5C,MAAI,yBAAyB,GAAG;AAC5B,UAAM,CAAC,KAAK,IAAI,QAAQ,SAAS,KAAK,MAAM,GAAG,EAAE,IAAI,MAAM;AAE3D,QAAI,SAAS,MAAO,UAAU,MAAM,SAAS,QAAQ,SAAS,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,KAAK,GAAI;AACrF,aAAO,CAAC;AAAA,IACZ;AACA,WAAO,CAAC,4BAA4B;AAAA,EACxC;AACA,SAAO,CAAC,YAAY,4BAA4B;AACpD;AAKO,SAAS,sBACZ,WACA,aAAgC,oBACxB;AAER,MAAI,WAAW,KAAK,SAAO,UAAU,SAAS,GAAG,CAAC,GAAG;AACjD,WAAO,CAAC,SAAS;AAAA,EACrB;AAGA,SAAO,WAAW,IAAI,SAAO,GAAG,SAAS,GAAG,GAAG,EAAE;AACrD;","names":[]}

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/register.js

@@ -0,0 +1,6 @@
+// src/register.ts
+import { register } from "module";
+import { pathToFileURL } from "url";
+register("./hooks.js", pathToFileURL(import.meta.url));
+console.log("[Flight Loader] TypeScript extension resolution enabled");
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/register.ts"],"sourcesContent":["/**\r\n * Auto-registration entry point for Node.js --import flag\r\n * \r\n * @example\r\n * ```bash\r\n * node --import @flightdev/loader/register ./server.js\r\n * ```\r\n */\r\n\r\nimport { register } from 'node:module';\r\nimport { pathToFileURL } from 'node:url';\r\n\r\n// Register the hooks\r\nregister('./hooks.js', pathToFileURL(import.meta.url));\r\n\r\nconsole.log('[Flight Loader] TypeScript extension resolution enabled');\r\n"],"mappings":";AASA,SAAS,gBAAgB;AACzB,SAAS,qBAAqB;AAG9B,SAAS,cAAc,cAAc,YAAY,GAAG,CAAC;AAErD,QAAQ,IAAI,yDAAyD;","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@flightdev/loader",
+  "version": "0.2.0",
+  "description": "Optional ESM loader for TypeScript extension resolution in Node.js",
+  "keywords": [
+    "flight",
+    "framework",
+    "loader",
+    "esm",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Flight Contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}