locter 4.0.0 → 4.1.1

package/README.MD

@@ -39,7 +39,7 @@
 - ✍️ **Write** — `write()` values back without pulling serializers into your app: comment-preserving YAML, indent-preserving JSON, rc9-style `.conf`.
 - 🔁 **Sync twins** — every operation ships as `fn` / `fnSync`, derived from one shared implementation.
 - 🧩 **Extensible** — register custom formats with independent reader/writer slots; override built-ins per extension.
-- 🚨 **Typed errors** — `LocterNotFoundError`, `LocterLoadError`, `LocterWriteError`, … each carrying `path` and `cause`.
+- 🚨 **Typed errors** — `NotFoundError`, `LoadError`, `WriteError`, … each carrying `path` and `cause`.
 
 **Table of Contents**
 
@@ -224,6 +224,28 @@ Bare module specifiers (no file extension) are routed to the module reader, so
 `read('yaml')` behaves like `import('yaml')` — note that reading a module
 **executes** it.
 
+**Per-call format override**
+
+Every read/write verb accepts an options object with a `format` key — a
+registered format id (a built-in: `module`, `conf`, `json`, `yaml`, `text` —
+or the id of a rule registered via `registerFormat`) used *instead* of
+extension dispatch. The most useful consequence: module files become readable
+**without being executed**:
+
+```typescript
+import { read } from 'locter';
+
+(async () => {
+    // the source of a module file — no evaluation, no side effects
+    const source = await read('vite.config.ts', { format: 'text' });
+
+    // extensionless files become readable, too
+    const license = await read('LICENSE', { format: 'text' });
+})
+```
+
+Unknown format ids throw `LocterError`.
+
 **Module records — `readAsModule`**
 
 Every `readAsModule` / `readAsModuleSync` result is a **module record** — a
@@ -293,7 +315,7 @@ import { readPackageField } from 'locter';
 })
 ```
 
-Throws `LocterLoadError` if the resolved `package.json` is malformed. A sync variant `readPackageFieldSync` is also available.
+Throws `LoadError` if the resolved `package.json` is malformed. A sync variant `readPackageFieldSync` is also available.
 
 ### Writer
 
@@ -331,7 +353,22 @@ Write semantics:
   brand — an `__esModule` key in plain data does **not** count) are unwrapped
   to their `.default` value before serialization.
 - Module formats (`.js`, `.ts`, …) are **read-only**: `write('config.ts', …)`
-  throws `LocterWriteError`, as does writing to a bare module specifier.
+  throws `WriteError`, as does writing to a bare module specifier.
+
+An explicit `format` id lifts both restrictions of the last bullet — naming
+the format resolves the ambiguity those guards exist for:
+
+```typescript
+import { write } from 'locter';
+
+(async () => {
+    // scaffold a module file from raw source ('text' bypasses read-only)
+    await write('generated/config.ts', 'export default {};', { format: 'text' });
+
+    // extensionless target, explicit format
+    await write('.myapprc', { port: 3000 }, { format: 'json' });
+})
+```
 
 Per-format behavior:
 
@@ -380,7 +417,7 @@ import { writePackageField } from 'locter';
 })
 ```
 
-Throws `LocterNotFoundError` when no `package.json` could be located. A sync
+Throws `NotFoundError` when no `package.json` could be located. A sync
 variant `writePackageFieldSync` is also available.
 
 ### Formats
@@ -509,24 +546,24 @@ 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 reader threw — parse error, runtime/eval error, etc.  |
-| `LocterWriteError`             | A write failed — serialization error, filesystem error, read-only format, corrupt existing YAML target |
-| `LocterUnknownExtensionError`  | No rule matched the file's extension                    |
+| `NotFoundError`                | File or module does not exist (`ENOENT`, `MODULE_NOT_FOUND`, `ERR_MODULE_NOT_FOUND`) |
+| `LoadError`                    | A reader threw — parse error, runtime/eval error, etc.  |
+| `WriteError`                   | A write failed — serialization error, filesystem error, read-only format, corrupt existing YAML target |
+| `UnknownExtensionError`        | 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 { read, LocterNotFoundError, LocterLoadError } from 'locter';
+import { read, NotFoundError, LoadError } from 'locter';
 
 try {
     await read('config.json');
 } catch (err) {
-    if (err instanceof LocterNotFoundError) {
+    if (err instanceof NotFoundError) {
         console.error(`Config file not found: ${err.path}`);
-    } else if (err instanceof LocterLoadError) {
+    } else if (err instanceof LoadError) {
         console.error(`Failed to parse config: ${err.cause}`);
     } else {
         throw err;
@@ -534,11 +571,11 @@ try {
 }
 ```
 
-Note that on the write side `ENOENT` stays a `LocterWriteError` — a missing
+Note that on the write side `ENOENT` stays a `WriteError` — a missing
 parent directory is a write failure, not a lookup miss (and `write` creates
 missing parents anyway).
 
-`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 reader) and a `toJSON()` for structured logging.
+`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 `NotFoundError`s thrown by the JSON reader) 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.
 
@@ -625,6 +662,7 @@ The list below is exhaustive — no other public APIs changed.
 | `ModuleLoader`                       | `ModuleReader`                             |
 | `setModuleLoader`                    | `setModuleReader`                          |
 | `loadPackageField` / `loadPackageFieldSync` | `readPackageField` / `readPackageFieldSync` |
+| `LocterLoadError` / `LocterNotFoundError` / `LocterUnknownExtensionError` | `LoadError` / `NotFoundError` / `UnknownExtensionError` — the `LocterError` base class keeps its name |
 
 **Behavioral changes:**
 
@@ -689,7 +727,7 @@ The list below is exhaustive — no other public APIs changed.
   `ConfWriter`), including comment-preserving YAML write-back — see
   [Writer](#writer).
 - `writePackageField` / `writePackageFieldSync`.
-- `LocterWriteError` + `wrapWriteError`.
+- `WriteError` + `wrapWriteError`.
 - `isModuleRecord` — brand-based detection of records produced by `read()`.
 - The ports are exported as `IReader` / `IWriter`, alongside `Rule`,
   `ReaderFactory`, `WriterFactory` — so custom formats can be typed against

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { BaseError, ErrorOptions } from "@ebec/core";
+import { TwinBody } from "twinop";
 import { createJiti } from "jiti";
 import { ToStringOptions } from "yaml";
 //#region src/errors/base.d.ts
@@ -15,21 +16,21 @@ declare class LocterError extends BaseError {
 //#endregion
 //#region src/errors/load.d.ts
 declare const LOCTER_LOAD_ERROR_MARKER: unique symbol;
-declare class LocterLoadError extends LocterError {
+declare class LoadError 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 {
+declare class NotFoundError 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 {
+declare class UnknownExtensionError extends LocterError {
   static [Symbol.hasInstance](input: unknown): boolean;
   constructor(input?: LocterErrorInput);
 }
@@ -40,7 +41,7 @@ declare function wrapWriteError(input: unknown, path: string): LocterError;
 //#endregion
 //#region src/errors/write.d.ts
 declare const LOCTER_WRITE_ERROR_MARKER: unique symbol;
-declare class LocterWriteError extends LocterError {
+declare class WriteError extends LocterError {
   static [Symbol.hasInstance](input: unknown): boolean;
   constructor(input?: LocterErrorInput);
 }
@@ -84,24 +85,6 @@ declare function locateUpSync(pattern: string | string[], options?: LocatorUpOpt
 declare function isLocatorInfo(input: unknown): input is LocatorInfo;
 declare function buildFilePath(input: LocatorInfo | string): string;
 //#endregion
-//#region src/utils/twin.d.ts
-/**
- * Internal protocol to derive the parallel sync + async public surfaces
- * from one shared body. A body is a generator that yields effect pairs —
- * an async and a sync thunk for the same operation — and the two drivers
- * (runTwinAsync / runTwinSync) execute the side they stand for. Effect
- * errors are re-entered into the body via `Generator.throw`, so try/catch
- * inside a body behaves identically in both variants.
- *
- * Deliberately NOT exported from the utils barrel — this is internal
- * plumbing, not public API.
- */
-type TwinOp<T = unknown> = {
-  async: () => Promise<T>;
-  sync: () => T;
-};
-type TwinBody<R> = Generator<TwinOp<any>, R, any>;
-//#endregion
 //#region src/format/type.d.ts
 interface IReader {
   read: (input: string) => Promise<any>;
@@ -131,7 +114,7 @@ declare abstract class TextFileReader implements IReader {
  * Base class for writers of text-based file formats: serializes via
  * `stringify`, creates missing parent directories, writes the file as
  * UTF-8 (always terminated by a single trailing newline), and wraps
- * failures in LocterWriteError. Subclasses implement `stringify` only —
+ * failures in WriteError. Subclasses implement `stringify` only —
  * both `write` variants are derived from the same body.
  */
 declare abstract class TextFileWriter implements IWriter {
@@ -296,7 +279,7 @@ type YAMLWriterOptions = ToStringOptions;
  * target file already exists, the new value is grafted into its parsed
  * document, so comments and anchors attached to surviving keys survive
  * the write-back. New files are plain `yaml.stringify` output. An
- * existing file that fails to parse throws (wrapped as LocterWriteError)
+ * existing file that fails to parse throws (wrapped as WriteError)
  * instead of being silently overwritten.
  */
 declare class YAMLWriter extends TextFileWriter {
@@ -379,13 +362,40 @@ type Rule = {
   /**
    * Stable identity. Registering an existing id REPLACES that rule in
    * place (position preserved, cached instance evicted). Built-in ids
-   * ('module', 'conf', 'json', 'yaml') are reserved. Omitted → auto-generated.
+   * ('module', 'conf', 'json', 'yaml', 'text') are reserved.
+   * Omitted → auto-generated.
    */
   id?: string;
   test: RegExp | string[];
   reader?: IReader | ReaderFactory;
   writer?: IWriter | WriterFactory;
 };
+/**
+ * Per-call options for read / readAsModule (+Sync).
+ */
+type ReadOptions = {
+  /**
+   * Read with the format registered under this id — a built-in id
+   * ('module', 'conf', 'json', 'yaml', 'text') or a user rule id —
+   * INSTEAD of dispatching by extension. This is the evaluation-free
+   * escape hatch for module files: read('config.ts', { format: 'text' })
+   * returns the source without executing it. Unknown ids throw.
+   */
+  format?: string;
+};
+/**
+ * Per-call options for write (+Sync).
+ */
+type WriteOptions = {
+  /**
+   * Write with the format registered under this id INSTEAD of
+   * dispatching by extension. Skips the bare-specifier guard, so
+   * extensionless paths become writable ('LICENSE' with 'text') and
+   * read-only extensions become targetable (raw source to a '.ts'
+   * file with 'text'). Read-only format ids and unknown ids throw.
+   */
+  format?: string;
+};
 /**
  * Normalized registration record — returned by register()/entries().
  */
@@ -472,36 +482,49 @@ declare class FormatRegistry {
    * normalized module record — a module IS a record, and the
    * normalization only irons out the CJS/ESM interop divergence so
    * both twin variants agree on one shape.
+   *
+   * options.format names a registered format id to use instead of
+   * extension dispatch (e.g. { format: 'text' } reads module source
+   * without evaluating it).
    */
-  read(input: LocatorInfo | string): Promise<any>;
-  readSync(input: LocatorInfo | string): any;
+  read(input: LocatorInfo | string, options?: ReadOptions): Promise<any>;
+  readSync(input: LocatorInfo | string, options?: ReadOptions): any;
   /**
    * Read a file/module and present the result as a normalized module
    * record — the uniform, frozen shape regardless of format:
    * `.default` always holds the loaded value, top-level keys are
    * re-exposed as named exports.
    */
-  readAsModule(input: LocatorInfo | string): Promise<any>;
-  readAsModuleSync(input: LocatorInfo | string): any;
-  protected readBody(input: LocatorInfo | string): TwinBody<any>;
-  protected readAsModuleBody(input: LocatorInfo | string): TwinBody<any>;
+  readAsModule(input: LocatorInfo | string, options?: ReadOptions): Promise<any>;
+  readAsModuleSync(input: LocatorInfo | string, options?: ReadOptions): any;
+  protected readBody(input: LocatorInfo | string, options: ReadOptions): TwinBody<any>;
+  protected readAsModuleBody(input: LocatorInfo | string, options: ReadOptions): TwinBody<any>;
   /**
    * Shared dispatch + execution of both read bodies: resolve the
    * reader, run it, wrap errors. Normalization is the caller's call.
    */
-  protected executeBody(input: LocatorInfo | string): TwinBody<{
+  protected executeBody(input: LocatorInfo | string, options: ReadOptions): TwinBody<{
     output: unknown;
     reader: IReader;
   }>;
-  write(input: LocatorInfo | string, value: unknown): Promise<void>;
-  writeSync(input: LocatorInfo | string, value: unknown): void;
+  /**
+   * options.format names a registered format id to use instead of
+   * extension dispatch — see writeBody for the boundary semantics.
+   */
+  write(input: LocatorInfo | string, value: unknown, options?: WriteOptions): Promise<void>;
+  writeSync(input: LocatorInfo | string, value: unknown, options?: WriteOptions): void;
   /**
    * Shared body of write/writeSync: dispatch, unwrap records, write, wrap.
    * The inverse boundary of readAsModuleBody: a record produced by
    * readAsModule() (brand detected) is unwrapped to its `.default` value;
    * anything else is written as-is.
+   *
+   * An explicit options.format skips extension dispatch entirely —
+   * including the bare-specifier guard: naming the format resolves the
+   * ambiguity the guard exists for, so extensionless paths become
+   * writable.
    */
-  protected writeBody(input: LocatorInfo | string, value: unknown): TwinBody<void>;
+  protected writeBody(input: LocatorInfo | string, value: unknown, options: WriteOptions): TwinBody<void>;
   /**
    * The single normalization boundary: every readAsModule result becomes a module
    * record (`.default` is always the loaded value, top-level keys stay
@@ -526,7 +549,7 @@ declare class FormatRegistry {
    *   1. bare specifier (no extension)  → module reader, always
    *   2. user rules, registration order → first match wins (can override built-ins)
    *   3. built-in extension table
-   *   4. undefined → read/readSync throw LocterUnknownExtensionError
+   *   4. undefined → read/readSync throw UnknownExtensionError
    */
   findReader(input: string): IReader | undefined;
   /**
@@ -535,9 +558,22 @@ declare class FormatRegistry {
    * presets that declare a writer.
    */
   findWriter(input: string): IWriter | undefined;
+  /**
+   * Resolve a reader by EXPLICIT format id (the per-call override) —
+   * a user rule id or a built-in id — bypassing extension dispatch.
+   * Unknown ids and writer-only rules throw.
+   */
+  protected resolveReader(id: string): IReader;
+  /**
+   * Write-side counterpart of resolveReader. Reader-only rules and
+   * read-only built-ins (module) throw WriteError, mirroring
+   * what extension dispatch throws for read-only extensions.
+   */
+  protected resolveWriter(id: string, path: string): IWriter;
   protected findRule(input: string, filter: (rule: CompiledRule) => boolean): CompiledRule | undefined;
   protected findBuiltInId(input: string): BuiltInFormatId | undefined;
-  protected unknownExtensionError(input: string): LocterUnknownExtensionError;
+  protected unknownExtensionError(input: string): UnknownExtensionError;
+  protected unknownFormatError(id: string): LocterError;
   protected compile(id: string, rule: Rule): CompiledRule;
   protected generateRuleId(): string;
 }
@@ -557,19 +593,28 @@ declare function unregisterFormat(id: string): boolean;
  * (json/yaml/conf and custom readers — mutable, round-trip-symmetric
  * with write); for modules the normalized module record (a module IS a
  * record; normalization only irons out CJS/ESM interop divergence).
+ *
+ * options.format forces a registered format id instead of extension
+ * dispatch — e.g. { format: 'text' } reads a module file's source
+ * WITHOUT evaluating it.
  */
-declare function read(input: LocatorInfo | string): Promise<any>;
-declare function readSync(input: LocatorInfo | string): any;
+declare function read(input: LocatorInfo | string, options?: ReadOptions): Promise<any>;
+declare function readSync(input: LocatorInfo | string, options?: ReadOptions): any;
 /**
  * Read a file/module and present the result as a normalized module
  * record — the uniform, frozen shape regardless of format: `.default`
  * always holds the loaded value, top-level keys are re-exposed as
  * named exports.
  */
-declare function readAsModule(input: LocatorInfo | string): Promise<any>;
-declare function readAsModuleSync(input: LocatorInfo | string): any;
-declare function write(input: LocatorInfo | string, value: unknown): Promise<void>;
-declare function writeSync(input: LocatorInfo | string, value: unknown): void;
+declare function readAsModule(input: LocatorInfo | string, options?: ReadOptions): Promise<any>;
+declare function readAsModuleSync(input: LocatorInfo | string, options?: ReadOptions): any;
+/**
+ * options.format forces a registered format id instead of extension
+ * dispatch — this also lifts the bare-specifier guard (extensionless
+ * paths) and the read-only block on module extensions.
+ */
+declare function write(input: LocatorInfo | string, value: unknown, options?: WriteOptions): Promise<void>;
+declare function writeSync(input: LocatorInfo | string, value: unknown, options?: WriteOptions): void;
 /**
  * Override the built-in module reader's `import` / `require` calls.
  *
@@ -609,7 +654,7 @@ declare function readPackageFieldSync<T = unknown>(field: string, options?: Read
  * Set a top-level field of the nearest `package.json` (same locate
  * semantics as readPackageField) and write it back, preserving the
  * file's existing indentation. Passing `undefined` removes the field.
- * Throws LocterNotFoundError when no package.json could be located.
+ * Throws NotFoundError when no package.json could be located.
  */
 declare function writePackageField(field: string, value: unknown, options?: WritePackageFieldOptions): Promise<void>;
 declare function writePackageFieldSync(field: string, value: unknown, options?: WritePackageFieldOptions): void;
@@ -640,5 +685,5 @@ declare function isVitestRuntimeEnvironment(): boolean;
 declare function isTsNodeRuntimeEnvironment(): boolean;
 declare function isTsxRuntimeEnvironment(): boolean;
 //#endregion
-export { ConfReader, ConfWriter, type FormatPreset, type FormatRegistration, FormatRegistry, type FormatRegistryOptions, type IReader, type IWriter, JSONReader, JSONWriter, type JSONWriterOptions, LOCTER_ERROR_MARKER, LOCTER_LOAD_ERROR_MARKER, LOCTER_NOT_FOUND_ERROR_MARKER, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER, LOCTER_WRITE_ERROR_MARKER, type LocatorInfo, type LocatorOptions, type LocatorOptionsInput, type LocatorUpOptionsInput, LocterError, type LocterErrorInput, type LocterErrorOptions, LocterLoadError, LocterNotFoundError, LocterUnknownExtensionError, LocterWriteError, MODULE_FILE_EXTENSIONS, type ModuleExport, type ModuleExportFilterFn, type ModuleLoadFn, type ModuleLoadOptions, type ModuleLoadSyncFn, ModuleReader, type ModuleReaderOptions, type ReadPackageFieldOptions, type ReaderFactory, type Rule, TextFileReader, TextFileWriter, TextReader, TextWriter, type WritePackageFieldOptions, type WriterFactory, YAMLReader, YAMLWriter, type YAMLWriterOptions, buildFilePath, deserializeValue, getFileNameExtension, getModuleExport, isJestRuntimeEnvironment, isLocatorInfo, isModuleRecord, isTsNodeRuntimeEnvironment, isTsxRuntimeEnvironment, isVitestRuntimeEnvironment, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, read, readAsModule, readAsModuleSync, readPackageField, readPackageFieldSync, readSync, registerFormat, removeFileNameExtension, serializeValue, setModuleReader, unregisterFormat, useFormatRegistry, wrapLoaderError, wrapWriteError, write, writePackageField, writePackageFieldSync, writeSync };
+export { ConfReader, ConfWriter, type FormatPreset, type FormatRegistration, FormatRegistry, type FormatRegistryOptions, type IReader, type IWriter, JSONReader, JSONWriter, type JSONWriterOptions, LOCTER_ERROR_MARKER, LOCTER_LOAD_ERROR_MARKER, LOCTER_NOT_FOUND_ERROR_MARKER, LOCTER_UNKNOWN_EXTENSION_ERROR_MARKER, LOCTER_WRITE_ERROR_MARKER, LoadError, type LocatorInfo, type LocatorOptions, type LocatorOptionsInput, type LocatorUpOptionsInput, LocterError, type LocterErrorInput, type LocterErrorOptions, MODULE_FILE_EXTENSIONS, type ModuleExport, type ModuleExportFilterFn, type ModuleLoadFn, type ModuleLoadOptions, type ModuleLoadSyncFn, ModuleReader, type ModuleReaderOptions, NotFoundError, type ReadOptions, type ReadPackageFieldOptions, type ReaderFactory, type Rule, TextFileReader, TextFileWriter, TextReader, TextWriter, UnknownExtensionError, WriteError, type WriteOptions, type WritePackageFieldOptions, type WriterFactory, YAMLReader, YAMLWriter, type YAMLWriterOptions, buildFilePath, deserializeValue, getFileNameExtension, getModuleExport, isJestRuntimeEnvironment, isLocatorInfo, isModuleRecord, isTsNodeRuntimeEnvironment, isTsxRuntimeEnvironment, isVitestRuntimeEnvironment, locate, locateMany, locateManySync, locateSync, locateUp, locateUpSync, read, readAsModule, readAsModuleSync, readPackageField, readPackageFieldSync, readSync, registerFormat, removeFileNameExtension, serializeValue, setModuleReader, unregisterFormat, useFormatRegistry, wrapLoaderError, wrapWriteError, write, writePackageField, writePackageFieldSync, writeSync };
 //# sourceMappingURL=index.d.mts.map