locter 2.2.0 → 3.0.0

package/README.MD

@@ -50,8 +50,8 @@ import { locateMany } from 'locter';
     console.log(files);
     /*
     [
-        { path: 'files', name: 'example', extension: '.js'},
-        { path: 'files', name: 'example', extension: '.ts'}
+        { directory: '/cwd/files', name: 'example', extension: '.js', path: '/cwd/files/example.js' },
+        { directory: '/cwd/files', name: 'example', extension: '.ts', path: '/cwd/files/example.ts' }
     ]
      */
 
@@ -62,9 +62,9 @@ import { locateMany } from 'locter';
     console.log(files);
     /*
     [
-        { path: 'files', name: 'example', extension: '.js'},
-        { path: 'files', name: 'example', extension: '.ts'},
-        { path: 'files', name: 'example-long', extension: '.ts'},
+        { directory: '/cwd/files', name: 'example', extension: '.js', path: '/cwd/files/example.js' },
+        { directory: '/cwd/files', name: 'example', extension: '.ts', path: '/cwd/files/example.ts' },
+        { directory: '/cwd/files', name: 'example-long', extension: '.ts', path: '/cwd/files/example-long.ts' }
     ]
      */
 })
@@ -86,13 +86,51 @@ import { locate } from 'locter';
 
     console.log(file);
     /*
-    { path: 'files', name: 'example', extension: '.js'}
+    { directory: '/cwd/files', name: 'example', extension: '.js', path: '/cwd/files/example.js' }
      */
 })
 ```
 
 A synchronous variant is also available: `locateSync`
 
+**Walking up**
+
+`locateUp` walks from a starting directory toward the filesystem root and returns the first match (useful for discovering config files at the repo root from any sub-directory):
+
+```typescript
+import { locateUp } from 'locter';
+
+(async () => {
+    const info = await locateUp('trapi.config.{ts,mts,cts,mjs,cjs,js,json}', {
+        cwd: process.cwd(),
+    });
+
+    console.log(info);
+    /*
+    { directory: '/repo', name: 'trapi.config', extension: '.ts', path: '/repo/trapi.config.ts' }
+    or `undefined` if nothing matched
+     */
+})
+```
+
+Pass `stopAt: '/repo'` to cap the walk at a known ceiling — inclusive, so the ceiling directory itself is still searched.
+
+A synchronous variant `locateUpSync` is also available.
+
+**Options**
+
+`locate` / `locateMany` (and their sync variants) accept an options object:
+
+| Option            | Type                    | Default         | Notes                                                  |
+|-------------------|-------------------------|-----------------|--------------------------------------------------------|
+| `cwd`             | `string \| string[]`    | `process.cwd()` | Working directory (or directories) the pattern is resolved against |
+| `ignore`          | `string \| string[]`    | `[]`            | Patterns to exclude                                    |
+| `onlyFiles`       | `boolean`               | `true`          | Match files only                                       |
+| `onlyDirectories` | `boolean`               | `false`         | Match directories only                                 |
+| `dot`             | `boolean`               | `false`         | Match dotfiles (e.g. `.env`, `.npmrc`) for wildcard patterns |
+
+`locateUp` / `locateUpSync` take the same options except `cwd` must be a single `string`, and additionally accept `stopAt?: string` (inclusive ceiling for the walk).
+
 ### Loader
 
 The `load` method can be used to load a file/module in an asynchronous fashion.
@@ -143,6 +181,31 @@ Two loaders are predefined from scratch and already registered:
 - **ModuleLoader**: This loader allows to load modules with
   `.js`, `.mjs`, `.mts`, `.cjs`, `.cts`, `.ts` file extensions independent of the environment (cjs or esm).
 
+**Reading a `package.json` field**
+
+`loadPackageField` reads a top-level field from the nearest `package.json` — handy for the common `pkg.<your-config-key>` config-loading fallback (vite's `pkg.vite`, eslint's `pkg.eslintConfig`, etc.):
+
+```typescript
+import { loadPackageField } from 'locter';
+
+(async () => {
+    const cwd = process.cwd();
+
+    const value = await loadPackageField<{ entry: string }>('myapp', { cwd });
+    // → the value of the `myapp` field, or undefined if package.json
+    //   or the field is absent.
+
+    // Walk parent directories until a package.json is found:
+    const parentValue = await loadPackageField('myapp', {
+        cwd,
+        walkUp: true,
+        stopAt: '/repo', // optional ceiling, inclusive
+    });
+})
+```
+
+Throws `LocterLoadError` if the resolved `package.json` is malformed. A sync variant `loadPackageFieldSync` is also available.
+
 To register loader for other file types, the function `registerLoader` can be used.
 
 ```typescript
@@ -158,6 +221,125 @@ registerLoader(['.ext'], {
 })
 ```
 
+### Errors
+
+`load` / `loadSync` (and every built-in loader) throw a typed subclass of
+`LocterError`, so callers can distinguish failure modes without substring
+matching on `.message`:
+
+| Class                          | When it's thrown                                        |
+|--------------------------------|---------------------------------------------------------|
+| `LocterNotFoundError`          | File or module does not exist (`ENOENT`, `MODULE_NOT_FOUND`, `ERR_MODULE_NOT_FOUND`) |
+| `LocterLoadError`              | A loader threw — parse error, runtime/eval error, etc.  |
+| `LocterUnknownExtensionError`  | No rule matched the file's extension                    |
+| `LocterError`                  | Base class; matches all of the above                    |
+
+Each error exposes the offending `path` and preserves the underlying error
+on `cause`:
+
+```typescript
+import { load, LocterNotFoundError, LocterLoadError } from 'locter';
+
+try {
+    await load('config.json');
+} catch (err) {
+    if (err instanceof LocterNotFoundError) {
+        console.error(`Config file not found: ${err.path}`);
+    } else if (err instanceof LocterLoadError) {
+        console.error(`Failed to parse config: ${err.cause}`);
+    } else {
+        throw err;
+    }
+}
+```
+
+`LocterError` extends [`BaseError`](https://github.com/Tada5hi/ebec) from `@ebec/core`, so each instance also carries a `code` (auto-derived from the class name unless overridden — e.g. `'ENOENT'` for `LocterNotFoundError`s thrown by the JSON loader) and a `toJSON()` for structured logging.
+
+Each error class also publishes its `Symbol.for(...)` marker (`LOCTER_ERROR_MARKER`, `LOCTER_NOT_FOUND_ERROR_MARKER`, …), which makes `instanceof` work across realms — useful when consumers end up with duplicate copies of locter in their dependency tree.
+
+### Migrating from 2.x
+
+The 3.0 release reshapes a few public surfaces. The list below is exhaustive — no other public APIs changed.
+
+```diff
+- import { load, locate } from 'locter';
++ import { load, locate, LocterNotFoundError, LocterLoadError } from 'locter';
+
+  // 1. LocatorOptions.path → cwd
+- await locate('config.json', { path: process.cwd() });
++ await locate('config.json', { cwd: process.cwd() });
+
+  // 2. LocatorInfo.path now holds the FULL file path (it was the
+  //    containing directory in 2.x). buildFilePath(info) still works in
+  //    both versions but is now a near-identity for LocatorInfo inputs.
+- const filePath = buildFilePath(info);  // 2.x: composed from .path + .name + .extension
++ const filePath = info.path;            // 3.x: just the path field
++ const dir      = info.directory;       // 3.x: containing directory (the old `info.path`)
+
+  // 3. load() / loadSync() (and every built-in loader) now throw
+  //    LocterError subclasses instead of generic Error / ebec BaseError.
+  try {
+      await load('config.json');
+- } catch (err) {
+-     if (err.message.includes('ENOENT')) { /* … */ }
++ } catch (err) {
++     if (err instanceof LocterNotFoundError) { /* … */ }
++     else if (err instanceof LocterLoadError) { /* parse error: err.cause */ }
++     else throw err;
+  }
+```
+
+Additionally:
+
+- The `ebec` runtime dependency is replaced by `@ebec/core`. If you used to import `BaseError` from `ebec`, switch to `@ebec/core`.
+- The package is now ESM-only (no `require('locter')`). This change shipped in the 2.x→3.x toolchain modernization commit; mentioned here for completeness.
+
+### Runtime environments
+
+Locter ships with two runtime detection helpers:
+
+- `isJestRuntimeEnvironment()` — true when running under Jest. Built-in: the
+  `ModuleLoader` falls back to `require()` under Jest to avoid a known
+  segmentation fault ([nodejs/node#35889](https://github.com/nodejs/node/issues/35889)).
+- `isVitestRuntimeEnvironment()` — true when running under Vitest (checks
+  `process.env.VITEST === 'true'`).
+
+#### Using locter with Vitest
+
+Locter's built-in `await import(id)` runs inside `node_modules/locter` and
+therefore bypasses Vitest's `vite-node` module graph by default. For most use
+cases this is fine, but it produces **duplicate module instances** when test
+code statically imports a module and locter dynamically loads the same module
+(or a transitive dependency of it). This breaks class identity for libraries
+that rely on it (e.g. TypeORM entity metadata).
+
+Use `setModuleLoader` to inject an `import` call from user space so Vitest can
+rewrite it:
+
+```typescript
+// vitest setup file
+import { setModuleLoader } from 'locter';
+
+setModuleLoader({
+    load: (id) => import(id),
+});
+```
+
+Alternatively, the same effect can be achieved by inlining locter in
+`vitest.config.ts`:
+
+```typescript
+export default defineConfig({
+    test: {
+        server: {
+            deps: {
+                inline: [/locter/],
+            },
+        },
+    },
+});
+```
+
 
 ## License
 

package/dist/index.d.mts

@@ -0,0 +1,244 @@
+import { BaseError, ErrorOptions } from "@ebec/core";
+import { createJiti } from "jiti";
+
+//#region src/errors/base.d.ts
+type LocterErrorOptions = ErrorOptions & {
+  path?: string;
+};
+type LocterErrorInput = string | LocterErrorOptions;
+declare const LOCTER_ERROR_MARKER: unique symbol;
+declare class LocterError extends BaseError {
+  static [Symbol.hasInstance](input: unknown): boolean;
+  readonly path?: string;
+  constructor(input?: LocterErrorInput);
+}
+//#endregion
+//#region src/errors/load.d.ts
+declare const LOCTER_LOAD_ERROR_MARKER: unique symbol;
+declare class LocterLoadError extends LocterError {
+  static [Symbol.hasInstance](input: unknown): boolean;
+  constructor(input?: LocterErrorInput);
+}
+//#endregion
+//#region src/errors/not-found.d.ts
+declare const LOCTER_NOT_FOUND_ERROR_MARKER: unique symbol;
+declare class LocterNotFoundError extends LocterError {
+  static [Symbol.hasInstance](input: unknown): boolean;
+  constructor(input?: LocterErrorInput);
+}
+//#endregion
+//#region src/errors/unknown-extension.d.ts
+declare const LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER: unique symbol;
+declare class LocterUnknownExtensionError extends LocterError {
+  static [Symbol.hasInstance](input: unknown): boolean;
+  constructor(input?: LocterErrorInput);
+}
+//#endregion
+//#region src/errors/wrap.d.ts
+declare function wrapLoaderError(input: unknown, path: string): LocterError;
+//#endregion
+//#region src/loader/type.d.ts
+type Loader = {
+  execute: (input: string) => Promise<any>;
+  executeSync: (input: string) => any;
+};
+type Rule = {
+  test: RegExp | string[];
+  loader: Loader | string;
+};
+//#endregion
+//#region src/loader/built-in/conf/module.d.ts
+declare class ConfLoader implements Loader {
+  execute(input: string): Promise<Record<string, any>>;
+  executeSync(input: string): Record<string, any>;
+  parse(contents: string): Record<string, any>;
+}
+//#endregion
+//#region src/loader/built-in/json/module.d.ts
+declare class JSONLoader implements Loader {
+  execute(input: string): Promise<any>;
+  executeSync(input: string): any;
+}
+//#endregion
+//#region src/locator/types.d.ts
+type LocatorInfo = {
+  directory: string;
+  name: string;
+  extension?: string;
+  path: string;
+};
+type LocatorOptions = {
+  cwd: string[];
+  ignore: string[];
+  onlyFiles: boolean;
+  onlyDirectories: boolean;
+  dot: boolean;
+};
+type LocatorOptionsInput = Partial<Omit<LocatorOptions, 'cwd' | 'ignore'>> & {
+  cwd?: string | string[];
+  ignore?: string | string[];
+};
+//#endregion
+//#region src/locator/async.d.ts
+declare function locateMany(pattern: string | string[], options?: LocatorOptionsInput): Promise<LocatorInfo[]>;
+declare function locate(pattern: string | string[], options?: LocatorOptionsInput): Promise<LocatorInfo | undefined>;
+//#endregion
+//#region src/locator/sync.d.ts
+declare function locateManySync(pattern: string | string[], options?: LocatorOptionsInput): LocatorInfo[];
+declare function locateSync(pattern: string | string[], options?: LocatorOptionsInput): LocatorInfo | undefined;
+//#endregion
+//#region src/locator/up.d.ts
+type LocatorUpOptionsInput = Omit<LocatorOptionsInput, 'cwd'> & {
+  cwd?: string;
+  stopAt?: string;
+};
+declare function locateUp(pattern: string | string[], options?: LocatorUpOptionsInput): Promise<LocatorInfo | undefined>;
+declare function locateUpSync(pattern: string | string[], options?: LocatorUpOptionsInput): LocatorInfo | undefined;
+//#endregion
+//#region src/locator/utils.d.ts
+declare function buildLocatorPatterns(pattern: string | string[]): string[];
+declare function buildLocatorOptions(options?: LocatorOptionsInput): LocatorOptions;
+declare function pathToLocatorInfo(input: string, skipResolve?: boolean): LocatorInfo;
+declare function isLocatorInfo(input: unknown): input is LocatorInfo;
+declare function buildFilePath(input: LocatorInfo | string): string;
+declare function buildFilePathWithoutExtension(input: LocatorInfo | string): string;
+//#endregion
+//#region src/loader/built-in/module/type.d.ts
+type LoaderFilterFn = (key: string, value: unknown) => boolean;
+type ModuleExport = {
+  key: string;
+  value: any;
+};
+type ModuleLoadOptions = {
+  withFilePrefix?: boolean;
+};
+type ModuleLoadFn = (id: string) => unknown | Promise<unknown>;
+type ModuleLoadSyncFn = (id: string) => unknown;
+type ModuleLoaderOptions = {
+  /**
+   * Custom asynchronous module loader. When set, this replaces the
+   * built-in `await import(id)` call. Useful for test runners (e.g. Vitest)
+   * where dynamic imports inside `node_modules/locter` would otherwise
+   * escape the runner's module graph — defining this in user space lets
+   * the runner rewrite the `import()`.
+   */
+  load?: ModuleLoadFn;
+  /**
+   * Custom synchronous module loader. When set, this replaces the built-in
+   * `require(id)` call.
+   */
+  loadSync?: ModuleLoadSyncFn;
+};
+//#endregion
+//#region src/loader/built-in/module/module.d.ts
+type Jiti = ReturnType<typeof createJiti>;
+declare class ModuleLoader implements Loader {
+  protected instance: Jiti;
+  protected loadFn?: ModuleLoadFn;
+  protected loadSyncFn?: ModuleLoadSyncFn;
+  constructor(options?: ModuleLoaderOptions);
+  configure(options: ModuleLoaderOptions): void;
+  execute(input: string): Promise<any>;
+  executeSync(input: string): any;
+  load(data: LocatorInfo | string, options?: ModuleLoadOptions): Promise<unknown>;
+  loadSync(data: LocatorInfo | string, options?: ModuleLoadOptions): unknown;
+  private build;
+}
+//#endregion
+//#region src/loader/built-in/module/utils.d.ts
+type ESModule = {
+  [key: string]: any;
+  __esModule: boolean;
+};
+declare function isESModule(input: unknown): input is ESModule;
+declare function toModuleRecord(data: unknown): any;
+declare function getModuleExport(data: Record<string, any>, filterFn: LoaderFilterFn): ModuleExport | undefined;
+//#endregion
+//#region src/loader/built-in/yaml/module.d.ts
+declare class YAMLLoader implements Loader {
+  execute(input: string): Promise<any>;
+  executeSync(input: string): any;
+}
+//#endregion
+//#region src/loader/helpers.d.ts
+declare function registerLoader(rule: Rule): void;
+declare function registerLoader(test: string[] | RegExp, loader: Loader): void;
+declare function load(input: LocatorInfo | string): Promise<any>;
+declare function loadSync(input: LocatorInfo | string): any;
+/**
+ * Override the built-in module loader's `import` / `require` calls.
+ *
+ * Useful for test runners (e.g. Vitest) where the dynamic `import()` inside
+ * `node_modules/locter` would bypass the runner's module graph. Calling this
+ * from user code (e.g. a Vitest setup file) lets the runner rewrite the
+ * `import()` so loaded modules share identity with statically imported ones.
+ *
+ * @example
+ * ```ts
+ * // vitest setup file
+ * import { setModuleLoader } from 'locter';
+ *
+ * setModuleLoader({
+ *     load: (id) => import(id),
+ * });
+ * ```
+ */
+declare function setModuleLoader(options: ModuleLoaderOptions): void;
+//#endregion
+//#region src/loader/module.d.ts
+declare class LoaderManager implements Loader {
+  protected loaders: Record<string, Loader>;
+  protected rules: Rule[];
+  constructor();
+  register(rule: Rule): void;
+  register(test: string[] | RegExp, loader: Loader): void;
+  execute(input: string): Promise<any>;
+  executeSync(input: string): any;
+  protected unknownExtensionError(input: string): LocterUnknownExtensionError;
+  findLoader(input: string): Loader | string | undefined;
+  /**
+   * Resolve loader by id.
+   *
+   * @param id
+   */
+  resolve(id: string | Loader): Loader;
+  normalizePath(input: string): string;
+}
+//#endregion
+//#region src/loader/package-field.d.ts
+type LoadPackageFieldOptions = {
+  cwd?: string;
+  walkUp?: boolean;
+  stopAt?: string;
+};
+declare function loadPackageField<T = unknown>(field: string, options?: LoadPackageFieldOptions): Promise<T | undefined>;
+declare function loadPackageFieldSync<T = unknown>(field: string, options?: LoadPackageFieldOptions): T | undefined;
+//#endregion
+//#region src/utils/file-name.d.ts
+declare function getFileNameExtension(input: string, allowed?: string[]): string | undefined;
+declare function removeFileNameExtension(input: string, extensions?: string[]): string;
+//#endregion
+//#region src/utils/has-property.d.ts
+declare function hasOwnProperty<X extends Record<string, any>, Y extends PropertyKey>(obj: X, prop: Y): obj is X & Record<Y, unknown>;
+declare function hasStringProperty<X extends Record<string, any>, Y extends PropertyKey>(obj: X, prop: Y): obj is X & Record<Y, string>;
+//#endregion
+//#region src/utils/object.d.ts
+declare function isObject(item: unknown): item is Record<string, any>;
+declare function isSafeObjectKey(key: string): boolean;
+//#endregion
+//#region src/utils/to-array.d.ts
+declare function toArray(input: string | string[]): string[];
+//#endregion
+//#region src/utils/file-path.d.ts
+declare function isFilePath(input: string): boolean | "";
+//#endregion
+//#region src/utils/runtime.d.ts
+declare function isJestRuntimeEnvironment(): boolean;
+declare function isVitestRuntimeEnvironment(): boolean;
+declare function isTsNodeRuntimeEnvironment(): boolean;
+//#endregion
+//#region src/utils/typescript.d.ts
+declare function isTypeScriptError(input: unknown): input is Error;
+//#endregion
+export { ConfLoader, JSONLoader, LOCTER_ERROR_MARKER, LOCTER_LOAD_ERROR_MARKER, LOCTER_NOT_FOUND_ERROR_MARKER, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER, LoadPackageFieldOptions, LoaderFilterFn, LoaderManager, LocatorInfo, LocatorOptions, LocatorOptionsInput, LocatorUpOptionsInput, LocterError, LocterErrorInput, LocterErrorOptions, LocterLoadError, LocterNotFoundError, LocterUnknownExtensionError, ModuleExport, ModuleLoadFn, ModuleLoadOptions, ModuleLoadSyncFn, ModuleLoader, ModuleLoaderOptions, YAMLLoader, buildFilePath, buildFilePathWithoutExtension, buildLocatorOptions, buildLocatorPatterns, getFileNameExtension, getModuleExport, hasOwnProperty, hasStringProperty, isESModule, isFilePath, isJestRuntimeEnvironment, isLocatorInfo, isObject, isSafeObjectKey, isTsNodeRuntimeEnvironment, isTypeScriptError, isVitestRuntimeEnvironment, load, loadPackageField, loadPackageFieldSync, loadSync, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, pathToLocatorInfo, registerLoader, removeFileNameExtension, setModuleLoader, toArray, toModuleRecord, wrapLoaderError };
+//# sourceMappingURL=index.d.mts.map