![\"locter\"](\"./assets/logo.svg\"){kind=logo}
\n\n \n
\n Locate, read & write files — one API.
\n Glob-based file discovery plus a pluggable format layer for JSON, YAML,\n .conf and TS/ESM/CJS modules — every operation sync and async.\n
\n ![\"npm](\"https://badge.fury.io/js/locter.svg\"){kind=icon}
\n ![\"CI\"](\"https://github.com/tada5hi/locter/actions/workflows/main.yml/badge.svg\"){kind=icon}
\n ![\"codecov\"](\"https://codecov.io/gh/Tada5hi/locter/branch/master/graph/badge.svg?token=4KNSG8L13V\"){kind=icon}
\n ![\"Known](\"https://snyk.io/test/github/Tada5hi/locter/badge.svg?targetFile=package.json\"){kind=icon}
\n ![\"Conventional](\"https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white\"){kind=icon}
\n Installation\n ·\n Usage\n ·\n Formats\n ·\n Errors\n ·\n Migration\n
\n\n---\n\n## Features\n\n- 🔍 **Locate** — `locate`, `locateMany`, `locateUp`: fast-glob discovery returning structured `LocatorInfo` records.\n- 📖 **Read** — one `read()` for JSON, YAML, `.conf`, and JS/TS modules in any runtime (powered by `jiti`); `readAsModule()` for the uniform module-record shape.\n- ✍️ **Write** — `write()` values back without pulling serializers into your app: comment-preserving YAML, indent-preserving JSON, rc9-style `.conf`.\n- 🔁 **Sync twins** — every operation ships as `fn` / `fnSync`, derived from one shared implementation.\n- 🧩 **Extensible** — register custom formats with independent reader/writer slots; override built-ins per extension.\n- 🚨 **Typed errors** — `NotFoundError`, `LoadError`, `WriteError`, … each carrying `path` and `cause`.\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [Usage](#usage)\n - [Locator](#locator)\n - [Reader](#reader)\n - [Writer](#writer)\n - [Formats](#formats)\n - [Errors](#errors)\n - [Runtime environments](#runtime-environments)\n- [Migration](#migration)\n - [Migrating from 3.x](#migrating-from-3x)\n - [Migrating from 2.x](#migrating-from-2x)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install locter --save\n```\n\n## Usage\n\nThe following examples are based on some shared assumptions:\n- A folder named `files` exists in the root directory.\n- The folder `files` contains the following files:\n - example.js\n - example.json\n - example.ts\n - example-long.ts\n\n\n### Locator\n\n**Multiple**\n\nLocating multiple files will return information about all files matching the pattern.\n\n```typescript\nimport { locateMany } from 'locter';\n\n(async () => {\n let files = await locateMany(\n 'files/example.{js,.ts}'\n );\n\n console.log(files);\n /*\n [\n { directory: '/cwd/files', name: 'example', extension: '.js', path: '/cwd/files/example.js' },\n { directory: '/cwd/files', name: 'example', extension: '.ts', path: '/cwd/files/example.ts' }\n ]\n */\n\n files = await locateMany(\n 'files/*.{js,ts}'\n );\n\n console.log(files);\n /*\n [\n { directory: '/cwd/files', name: 'example', extension: '.js', path: '/cwd/files/example.js' },\n { directory: '/cwd/files', name: 'example', extension: '.ts', path: '/cwd/files/example.ts' },\n { directory: '/cwd/files', name: 'example-long', extension: '.ts', path: '/cwd/files/example-long.ts' }\n ]\n */\n})\n```\n\nA synchronous variant is also available: `locateManySync`\n\n**Single**\n\nLocating a single file will return information about the first file matching the pattern.\n\n```typescript\nimport { locate } from 'locter';\n\n(async () => {\n let file = await locate(\n 'files/example.{js,.ts}'\n );\n\n console.log(file);\n /*\n { directory: '/cwd/files', name: 'example', extension: '.js', path: '/cwd/files/example.js' }\n */\n})\n```\n\nA synchronous variant is also available: `locateSync`\n\n**Walking up**\n\n`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):\n\n```typescript\nimport { locateUp } from 'locter';\n\n(async () => {\n const info = await locateUp('trapi.config.{ts,mts,cts,mjs,cjs,js,json}', {\n cwd: process.cwd(),\n });\n\n console.log(info);\n /*\n { directory: '/repo', name: 'trapi.config', extension: '.ts', path: '/repo/trapi.config.ts' }\n or `undefined` if nothing matched\n */\n})\n```\n\nPass `stopAt: '/repo'` to cap the walk at a known ceiling — inclusive, so the ceiling directory itself is still searched.\n\nA synchronous variant `locateUpSync` is also available.\n\n**Options**\n\n`locate` / `locateMany` (and their sync variants) accept an options object:\n\n| Option | Type | Default | Notes |\n|-------------------|-------------------------|-----------------|--------------------------------------------------------|\n| `cwd` | `string \\| string[]` | `process.cwd()` | Working directory (or directories) the pattern is resolved against |\n| `ignore` | `string \\| string[]` | `[]` | Patterns to exclude |\n| `onlyFiles` | `boolean` | `true` | Match files only |\n| `onlyDirectories` | `boolean` | `false` | Match directories only |\n| `dot` | `boolean` | `false` | Match dotfiles (e.g. `.env`, `.npmrc`) for wildcard patterns |\n\nIf both flags are set, `onlyDirectories: true` takes precedence over `onlyFiles`; when neither restricts the match (`onlyFiles: false`), files **and** directories are returned.\n\n`locateUp` / `locateUpSync` take the same options except `cwd` must be a single `string`, and additionally accept `stopAt?: string` (inclusive ceiling for the walk).\n\n**File-name helpers**\n\nTwo small helpers for working with the extensions locter routes on:\n\n```typescript\nimport { getFileNameExtension, removeFileNameExtension } from 'locter';\n\ngetFileNameExtension('seed.ts'); // '.ts'\ngetFileNameExtension('seed.ts', ['.js', '.mjs']); // undefined (not allowed)\n\nremoveFileNameExtension('seed.ts'); // 'seed'\nremoveFileNameExtension('seed.ts', ['.js']); // 'seed.ts' (not matched)\n```\n\n### Reader\n\nTwo verbs, two shapes:\n\n- **`read`** — *raw*: the plain parsed value for data formats (JSON/YAML/Conf\n and custom readers) — mutable and round-trip-symmetric with `write`. For\n modules it returns the normalized module record: a module *is* a record,\n and the normalization only irons out the CJS/ESM interop divergence so\n `read` and `readSync` agree on one shape.\n- **`readAsModule`** — everything as a *module record*: the uniform, frozen\n record shape regardless of format — for export inspection, interop, and\n uniform handling of mixed-extension config.\n\nEither a string or the output of the locate/locateSync method can be passed\nas argument; both verbs have `*Sync` twins.\n\n```typescript\nimport { locate, read, readSync } from 'locter';\n\n(async () => {\n const config = await read('config.yml');\n // → the plain parsed value: { port: 3000, ... } — mutable,\n // round-trip-symmetric with write()\n\n const settings = await read('trapi.config.ts');\n // → the module as a normalized record; unwrap explicitly:\n // settings.default\n\n const file = await locate('files/example.{js,.ts}');\n const content = readSync(file); // sync twin\n})\n```\n\nBare module specifiers (no file extension) are routed to the module reader, so\n`read('yaml')` behaves like `import('yaml')` — note that reading a module\n**executes** it.\n\n**Per-call format override**\n\nEvery read/write verb accepts an options object with a `format` key — a\nregistered format id (a built-in: `module`, `conf`, `json`, `yaml`, `text` —\nor the id of a rule registered via `registerFormat`) used *instead* of\nextension dispatch. The most useful consequence: module files become readable\n**without being executed**:\n\n```typescript\nimport { read } from 'locter';\n\n(async () => {\n // the source of a module file — no evaluation, no side effects\n const source = await read('vite.config.ts', { format: 'text' });\n\n // extensionless files become readable, too\n const license = await read('LICENSE', { format: 'text' });\n})\n```\n\nUnknown format ids throw `LocterError`.\n\n**Module records — `readAsModule`**\n\nEvery `readAsModule` / `readAsModuleSync` result is a **module record** — a\nfrozen, null-prototype object shaped like an ES module namespace: `default`\nalways holds the loaded value, and when that value is an object, its\ntop-level keys are re-exposed as named exports. For modules, `read` and\n`readAsModule` agree; for data formats, `read` returns what\n`readAsModule(...).default` holds.\n\n```typescript\nimport { readAsModule } from 'locter';\n\n(async () => {\n const pkg = await readAsModule('package.json');\n\n console.log(pkg.default); // the full parsed JSON value\n console.log(pkg.version); // top-level keys are named exports\n})\n```\n\nFor JavaScript/TypeScript files the module's own namespace passes through\nunchanged; the output of every other reader (built-in JSON/YAML/Conf and\nuser-registered ones) is always wrapped — even if the parsed data happens to\ncontain an `__esModule` key (`read` of such data likewise returns it\nuntouched — a literal `__esModule` key never turns data into a module).\nThe record is read-only: to mutate the loaded data, work with `.default`\n(for data records that is the same object `read` returns).\n\nRecords additionally carry a private, non-forgeable brand: `isModuleRecord`\ntells records produced by `readAsModule()` apart from arbitrary data, and\n[`write`](#writer) uses the brand to unwrap `.default` automatically on\nwrite-back.\n\nTo pick an export by predicate, the `getModuleExport` helper is available:\n\n```typescript\nimport { getModuleExport, readAsModule } from 'locter';\n\n(async () => {\n const record = await readAsModule('files/example.ts');\n\n const found = getModuleExport(record, (key) => key === 'myExport');\n // → { key: 'myExport', value: ... }, or undefined if no key matches\n})\n```\n\n**Reading a `package.json` field**\n\n`readPackageField` reads a top-level field from the nearest `package.json` — handy for the common `pkg.