load-oxfmt-config 0.0.7 → 0.1.0

package/README.md

@@ -5,7 +5,15 @@
 [![NPM DOWNLOADS](https://img.shields.io/npm/dy/load-oxfmt-config.svg)](https://www.npmjs.com/package/load-oxfmt-config)
 [![LICENSE](https://img.shields.io/github/license/ntnyq/load-oxfmt-config.svg)](https://github.com/ntnyq/load-oxfmt-config/blob/main/LICENSE)
 
-Load .oxfmtrc.json(c) for oxfmt.
+> Load and resolve `.oxfmtrc.json(c)` configuration files for [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html).
+
+## Features
+
+- 🔍 **Auto-discovery** - Automatically searches for config files in current and parent directories
+- 📦 **Multiple formats** - Supports both `.oxfmtrc.json` and `.oxfmtrc.jsonc` (JSON with comments)
+- ⚡ **Built-in caching** - Caches both file resolution and parsed configs for optimal performance
+- 🎯 **TypeScript support** - Fully typed with comprehensive type definitions
+- 🛠️ **Flexible API** - Support explicit config paths or automatic discovery
 
 ## Install
 
@@ -23,41 +31,205 @@ pnpm add load-oxfmt-config
 
 ## Usage
 
+### Basic Usage
+
+Load config from current directory or parent directories:
+
+```ts
+import { loadOxfmtConfig } from 'load-oxfmt-config'
+
+// Automatically searches for .oxfmtrc.json(c) in current and parent directories
+const config = await loadOxfmtConfig()
+console.log(config) // { printWidth: 80, ... }
+```
+
+### Specify Working Directory
+
+```ts
+import { loadOxfmtConfig } from 'load-oxfmtConfig'
+
+const config = await loadOxfmtConfig({
+  cwd: '/path/to/project',
+})
+```
+
+### Explicit Config Path
+
+```ts
+import { loadOxfmtConfig } from 'load-oxfmt-config'
+
+// Relative path (resolved relative to cwd)
+const config = await loadOxfmtConfig({
+  configPath: 'configs/.oxfmtrc.json',
+  cwd: '/path/to/project',
+})
+
+// Absolute path
+const config = await loadOxfmtConfig({
+  configPath: '/absolute/path/to/.oxfmtrc.json',
+})
+```
+
+### Disable Caching
+
 ```ts
 import { loadOxfmtConfig } from 'load-oxfmt-config'
 
+// Force reload from disk, bypassing cache
 const config = await loadOxfmtConfig({
-  cwd: '/configs',
+  useCache: false,
 })
+```
 
-console.log({ config })
+### Path Resolution Only
+
+```ts
+import { resolveOxfmtrcPath } from 'load-oxfmt-config'
+
+// Only resolve the config file path without loading it
+const configPath = await resolveOxfmtrcPath(process.cwd())
+console.log(configPath) // '/path/to/.oxfmtrc.json' or undefined
 ```
 
+## API
+
+### `loadOxfmtConfig(options?)`
+
+Load and parse oxfmt configuration file.
+
+**Parameters:**
+
+- `options` - Optional configuration object
+
+**Returns:** `Promise<FormatOptions>` - Parsed oxfmt configuration object. Returns empty object `{}` if no config file is found.
+
+**Throws:** Error if config file exists but cannot be parsed.
+
+### `resolveOxfmtrcPath(cwd, configPath?)`
+
+Resolve the absolute path to oxfmt config file.
+
+**Parameters:**
+
+- `cwd` - Starting directory for resolution
+- `configPath` - Optional explicit path (absolute or relative to cwd)
+
+**Returns:** `Promise<string | undefined>` - Absolute path to config file, or `undefined` if not found.
+
 ## Options
 
-### configPath
+All options are optional.
+
+### `cwd`
+
+- **Type:** `string`
+- **Default:** `process.cwd()`
+
+Current working directory to start searching for config files. The loader will walk up from this directory to find a config file.
+
+### `configPath`
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Explicit path to the config file:
+
+- **Relative path:** Resolved relative to `cwd`
+- **Absolute path:** Used as-is
+- **When provided:** Skips auto-discovery and uses this path directly
+
+### `useCache`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Enable in-memory caching for both path resolution and parsed config contents. When enabled:
+
+- Config file paths are cached to avoid repeated filesystem lookups
+- Parsed config objects are cached to avoid re-parsing
+- Subsequent calls with the same parameters return cached results instantly
+
+Set to `false` to force reload from disk on every call.
+
+## Config File Discovery
+
+When `configPath` is not provided, the loader automatically searches for config files:
+
+1. **Search order:** Starts from `cwd` and walks up to parent directories
+2. **Supported filenames:**
+   - `.oxfmtrc.json`
+   - `.oxfmtrc.jsonc`
+3. **Stops when:**
+   - A valid config file is found
+   - Reaches the filesystem root
+4. **Returns:** Empty object `{}` if no config file is found
+
+## Supported Config Formats
+
+### JSON (`.oxfmtrc.json`)
+
+```json
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true
+}
+```
+
+### JSONC (`.oxfmtrc.jsonc`)
+
+JSON with comments support:
+
+```jsonc
+{
+  // Formatting options
+  "printWidth": 100,
+  "tabWidth": 2,
+
+  /* Code style preferences */
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true
+}
+```
+
+## Error Handling
+
+```ts
+import { loadOxfmtConfig } from 'load-oxfmt-config'
+
+try {
+  const config = await loadOxfmtConfig()
+} catch (error) {
+  // Thrown when config file exists but contains invalid JSON
+  console.error('Failed to parse oxfmt config:', error.message)
+}
+```
+
+## Caching Behavior
 
-**Type**: `string`\
-**Required**: `false`\
-**Default**: `undefined`
+The caching system maintains two separate caches:
 
-Path to the oxfmt config file, resolved relative to `cwd`.
+1. **Path Resolution Cache:** Stores resolved config file paths
+2. **Config Content Cache:** Stores parsed configuration objects
 
-### cwd
+**Cache keys are based on:**
 
-**Type**: `string`\
-**Required**: `false`\
-**Default**: `process.cwd()`
+- `cwd` + `configPath` for path resolution
+- Resolved file path for config content
 
-Current working directory used when searching for config files.
+**Cache invalidation:**
 
-### useCache
+- Failed operations automatically clear their cache entries
+- Use `useCache: false` to bypass cache for specific calls
+- Cache persists for the lifetime of the Node.js process
 
-**Type**: `boolean`\
-**Required**: `false`\
-**Default**: `true`
+## Related
 
-Enable in-memory caching for path resolution and parsed config contents.
+- [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) - The Oxidation Compiler formatter
+- [oxc](https://oxc.rs/) - The JavaScript Oxidation Compiler
 
 ## License
 

package/dist/index.d.mts

@@ -3,16 +3,16 @@ import { FormatOptions } from "oxfmt";
 //#region src/types.d.ts
 interface Options {
   /**
-       * Path to the configuration file
-       */
+   * Path to the configuration file
+   */
   configPath?: string;
   /**
-       * Current working directory
-       */
+   * Current working directory
+   */
   cwd?: string;
   /**
-       * Whether to use cache
-       */
+   * Whether to use cache
+   */
   useCache?: boolean;
 }
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "load-oxfmt-config",
   "type": "module",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "Load .oxfmtrc.json(c) for oxfmt.",
   "keywords": [
     "jsonc-parser",
@@ -38,39 +38,40 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "oxfmt": "^0.26.0"
+    "oxfmt": "0.x"
   },
   "dependencies": {
     "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^5.9.0",
-    "@ntnyq/prettier-config": "^3.0.1",
+    "@ntnyq/eslint-config": "^6.0.0-beta.6",
     "@ntnyq/tsconfig": "^3.1.0",
-    "@types/node": "^25.0.9",
+    "@types/node": "^25.2.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260202.1",
     "bumpp": "^10.4.0",
     "eslint": "^9.39.2",
     "husky": "^9.1.7",
     "nano-staged": "^0.9.0",
     "npm-run-all2": "^8.0.4",
-    "oxfmt": "^0.26.0",
-    "prettier": "^3.8.0",
-    "tsdown": "^0.20.0-beta.3",
+    "oxfmt": "^0.28.0",
+    "tsdown": "^0.20.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   },
   "nano-staged": {
     "*.{js,ts,mjs,cjs,md,vue,yml,yaml,toml,json}": "eslint --fix",
-    "*.{css,scss,html}": "prettier -uw"
+    "*": "oxfmt --no-error-on-unmatched-pattern"
   },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
     "lint": "eslint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
     "release": "run-s release:check release:version",
-    "release:check": "run-s lint typecheck test",
+    "release:check": "run-s format:check lint typecheck test",
     "release:version": "bumpp",
     "test": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsgo --noEmit"
   }
 }