@powerduck/conf-patch 0.3.3 → 0.3.4

package/README.md

@@ -1,17 +1,21 @@
 # @powerduck/conf-patch
 
-Production-grade configuration file editor with a clean two-layer architecture: a browser-safe core layer for patching JSON/JSONC/YAML strings, and a Node.js/Electron file layer with atomic writes and cross-process file locking.
-
 [![npm version](https://img.shields.io/npm/v/@powerduck/conf-patch)](https://www.npmjs.com/package/@powerduck/conf-patch)
 [![license](https://img.shields.io/npm/l/@powerduck/conf-patch)](https://github.com/PowerDuckie/conf-patch/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/@powerduck/conf-patch)](https://www.npmjs.com/package/@powerduck/conf-patch)
 
-## Links
+Production-grade configuration file editor with a clean two-layer architecture: a browser-safe core layer for patching JSON/JSONC/YAML strings, and a Node.js/Electron file layer with atomic writes and cross-process file locking.
 
-- [Official Website](https://www.powerduck.com/opensource/conf-patch.html)
-- [Documentation](https://www.powerduck.com/docs/conf-patch/introduction)
-- [Live Demo](https://www.powerduck.com/demo/conf-patch.html)
-- [GitHub](https://github.com/PowerDuckie/conf-patch)
-- [npm](https://www.npmjs.com/package/@powerduck/conf-patch)
+---
+
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
+
+- **Core Layer** — Browser-safe patching for JSON, JSONC, and YAML strings with no filesystem dependency
+- **File Layer** — Atomic writes with temp-file + rename, cross-process file locking for Node.js/Electron
+- **RFC 6902 JSON Patch** — `add`, `replace`, and `remove` operations with strict/non-strict modes
+- **OpenAPI Validation** — Built on `@powerduck/openapi-parser` with secure input handling and DoS guards
+- **Comment-Preserving Edits** — JSONC edits are range-based, preserving comments and trailing commas
+- **Dual ESM/CJS** — Works with `import` and `require`, with bundled TypeScript declarations
 
 ---
 
@@ -23,7 +27,7 @@ Production-grade configuration file editor with a clean two-layer architecture:
 npm install @powerduck/conf-patch
 ```
 
-### Patch a JSON string (browser-safe, no filesystem)
+### Patch a JSON string (browser-safe)
 
 ```typescript
 import { patchContent } from "@powerduck/conf-patch/core";
@@ -38,45 +42,26 @@ const updated = patchContent(
 );
 
 console.log(updated);
-// {
-//   "name": "app",
-//   "version": "2.0.0",
-//   "description": "My application"
-// }
 ```
 
 ### Set a value in a file (Node.js / Electron)
 
 ```typescript
-import { setConfigValue, readConfigFile } from "@powerduck/conf-patch";
+import { setConfigValue } from "@powerduck/conf-patch";
 
 // Atomic write with file locking
 await setConfigValue("config.yaml", ["database", "port"], 5432);
-
-const content = await readConfigFile("config.yaml");
-console.log(content);
 ```
 
-### Validate an OpenAPI document
+---
 
-```typescript
-import { validateOpenAPISpec, OpenApiValidationError } from "@powerduck/conf-patch";
+## Links
 
-try {
-  const doc = await validateOpenAPISpec(`
-    openapi: 3.1.0
-    info:
-      title: Demo API
-      version: 1.0.0
-    paths: {}
-  `);
-  console.log("Valid. openapi =", doc.openapi);
-} catch (error) {
-  if (error instanceof OpenApiValidationError) {
-    console.error(`[${error.code}]`, error.message);
-  }
-}
-```
+- [Official Website](https://www.powerduck.com/opensource/conf-patch.html)
+- [Documentation](https://www.powerduck.com/docs/conf-patch/introduction)
+- [Live Demo](https://www.powerduck.com/demo/conf-patch)
+- [GitHub](https://github.com/PowerDuckie/conf-patch)
+- [npm](https://www.npmjs.com/package/@powerduck/conf-patch)
 
 ---
 
@@ -119,178 +104,212 @@ try {
 
 Import from `@powerduck/conf-patch/core` for pure string operations with no filesystem access.
 
-### `patchContent(content, ops, format, options?)`
+### `patchContent(content, operations, format)`
+
+Patches a JSON/JSONC/YAML string with RFC 6902 operations.
 
 ```typescript
-function patchContent(
-  content: string,
-  ops: JsonPatchOp[],
-  format: ConfigFormat,
-  options?: PatchContentOptions,
-): string;
+import { patchContent } from "@powerduck/conf-patch/core";
+
+const result = patchContent(
+  '{"a": 1, "b": 2}',
+  [{ op: "replace", path: ["a"], value: 10 }],
+  "json",
+);
 ```
 
-Applies an array of RFC 6902 patch operations. Returns the patched content.
+### `setContentValue(content, path, value, format)`
 
-| Parameter | Type | Description |
-|---|---|---|
-| `content` | `string` | The raw configuration content |
-| `ops` | `JsonPatchOp[]` | Operations to apply in order |
-| `format` | `ConfigFormat` | `"json" \| "jsonc" \| "yaml"` |
-| `options.strict` | `boolean` | When `true` (default), failed operations throw. When `false`, skipped with a warning. |
+Convenience function to set a single value at a path.
 
-### `setContentValue(content, path, value, format)`
+```typescript
+import { setContentValue } from "@powerduck/conf-patch/core";
 
-Sets or creates a single value. Internally calls `patchContent` with one `add` operation.
+const result = setContentValue(
+  '{"server": {"port": 3000}}',
+  ["server", "port"],
+  8080,
+  "json",
+);
+```
 
 ### `deleteContentValue(content, path, format)`
 
-Removes a key or array element. The path must exist.
+Delete a value at a path.
 
----
-
-## File Layer (Node.js / Electron)
+```typescript
+import { deleteContentValue } from "@powerduck/conf-patch/core";
 
-Import from the main entry `@powerduck/conf-patch`.
+const result = deleteContentValue('{"a": 1, "b": 2}', ["b"], "json");
+```
 
-### `readConfigFile(filePath)`
+### `detectFormat(filePath)`
 
-Reads UTF-8 text from a local file path or `file://` URL.
+Detect format from file extension.
 
-### `writeConfigFile(filePath, content, options?)`
+```typescript
+import { detectFormat } from "@powerduck/conf-patch";
 
-Writes content using an atomic write (temp file + rename) and exclusive file locking.
+const format = detectFormat("./config.yaml"); // "yaml"
+```
 
-### `patchConfigFile(filePath, ops, options?)`
+---
 
-The primary file-layer transaction: read the file inside a lock, apply `patchContent`, and write back atomically only if the content changed.
+## File Layer (Node.js / Electron)
 
-### `setConfigValue(filePath, path, value, options?)`
+Import from `@powerduck/conf-patch` for filesystem operations with atomic writes and file locking.
 
-Adds or replaces a nested value in a file.
+### `readConfigFile(filePath, options?)`
 
-### `deleteConfigValue(filePath, path, options?)`
+Read and parse a config file.
 
-Removes an existing nested value from a file.
+```typescript
+import { readConfigFile } from "@powerduck/conf-patch";
 
-### `withFileLock(filePath, callback, options?)`
+const config = await readConfigFile("./config.json");
+console.log(config.value);
+```
 
-Runs an async callback under a process-local queue and an exclusive lock file.
+### `writeConfigFile(filePath, value, options?)`
 
----
+Write a config value to a file with atomic write.
 
-## OpenAPI Validation
+```typescript
+import { writeConfigFile } from "@powerduck/conf-patch";
 
-### `validateOpenAPISpec(input, options?)`
+await writeConfigFile("./config.json", { name: "app", version: "1.0.0" });
+```
 
-Validates raw OpenAPI/Swagger content (JSON or YAML). Returns the validated document on success, throws `OpenApiValidationError` on failure.
+### `setConfigValue(filePath, path, value, options?)`
 
-### `validateOpenAPIFile(filePath, options?)`
+Set a single value in a config file with atomic write and file locking.
 
-Convenience wrapper that validates from a file path. Requires `allowedRootDirectory` for path sandboxing.
+```typescript
+import { setConfigValue } from "@powerduck/conf-patch";
 
-### `OpenApiValidationError`
+await setConfigValue("./config.yaml", ["database", "host"], "localhost");
+```
 
-Structured error with a machine-readable `code` property:
+### `patchConfigFile(filePath, operations, options?)`
 
-| Code | Meaning |
-|---|---|
-| `INVALID_OPTION` | Invalid option value provided |
-| `INPUT_TOO_LARGE` | Raw content exceeds `maxInputBytes` |
-| `FILE_INPUT_FORBIDDEN` | File input used without `allowedRootDirectory` |
-| `PATH_OUTSIDE_ROOT` | File path resolves outside `allowedRootDirectory` |
-| `PARSE_ERROR` | Failed to parse JSON/YAML content |
-| `UNSUPPORTED_VERSION` | Document does not declare a supported OpenAPI/Swagger version |
-| `SPEC_VALIDATION_FAILED` | The spec failed OpenAPI validation |
-| `OPERATION_TIMEOUT` | Operation exceeded `timeoutMs` |
-| `OPERATION_ABORTED` | Operation was aborted via `signal` |
+Apply RFC 6902 patch operations to a config file.
 
----
+```typescript
+import { patchConfigFile } from "@powerduck/conf-patch";
 
-## Types
+await patchConfigFile("./config.json", [
+  { op: "replace", path: ["version"], value: "2.0.0" },
+  { op: "add", path: ["author"], value: "Powerduck" },
+]);
+```
 
-```typescript
-type ConfigFormat = "json" | "jsonc" | "yaml";
+### `withFileLock(filePath, callback, options?)`
 
-interface JsonPatchOp {
-  op: "add" | "replace" | "remove";
-  path: (string | number)[];
-  value?: unknown; // Required for "add" and "replace"
-}
+Acquire a file lock and execute a callback.
 
-interface PatchContentOptions {
-  strict?: boolean; // default: true
-}
+```typescript
+import { withFileLock } from "@powerduck/conf-patch";
 
-interface PatchConfigOptions {
-  format?: ConfigFormat;
-  strict?: boolean;
-  lock?: boolean;
-  lockTimeoutMs?: number;
-  lockRetryDelayMs?: number;
-  lockStaleThresholdMs?: number;
-  allowStaleRecovery?: boolean;
-}
+await withFileLock("./config.json", async () => {
+  // Critical section - no other process can modify the file
+  await setConfigValue("./config.json", ["counter"], 42);
+});
 ```
 
 ---
 
-## Electron IPC Example
+## OpenAPI Validation
 
-```javascript
-// Electron main process (CommonJS)
-const { setConfigValue, readConfigFile } = require("@powerduck/conf-patch");
+Built-in OpenAPI spec validation with secure input handling.
 
-ipcMain.handle("config:set", async (_event, { filePath, path, value }) => {
-  try {
-    await setConfigValue(filePath, path, value);
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: error.message };
-  }
-});
+### `validateOpenAPISpec(input, options?)`
+
+Validate a raw YAML or JSON OpenAPI document.
 
-ipcMain.handle("config:read", async (_event, { filePath }) => {
-  try {
-    const data = await readConfigFile(filePath);
-    return { success: true, data };
-  } catch (error) {
-    return { success: false, error: error.message };
+```typescript
+import {
+  validateOpenAPISpec,
+  OpenApiValidationError,
+} from "@powerduck/conf-patch";
+
+try {
+  const doc = await validateOpenAPISpec(`
+    openapi: 3.1.0
+    info:
+      title: Demo API
+      version: 1.0.0
+    paths: {}
+  `);
+  console.log("Valid. openapi =", doc.openapi);
+} catch (error) {
+  if (error instanceof OpenApiValidationError) {
+    console.error(`[${error.code}]`, error.message);
   }
-});
+}
 ```
 
----
+### `validateOpenAPIFile(filePath, options?)`
 
-## Development
+Validate an OpenAPI document from a local file.
 
-```bash
-# Install dependencies
-npm install
+```typescript
+import { validateOpenAPIFile } from "@powerduck/conf-patch";
 
-# Type check
-npm run typecheck
+const doc = await validateOpenAPIFile("./openapi.json", {
+  allowedRootDirectory: "./specs",
+  maxInputBytes: 5 * 1024 * 1024,
+});
+```
 
-# Build (ESM + CJS + type declarations)
-npm run build
+### Validation Options
 
-# Run tests
-npm test
+| Option                 | Type                  | Default     | Description                                                 |
+| ---------------------- | --------------------- | ----------- | ----------------------------------------------------------- |
+| `inputKind`            | `"content" \| "file"` | `"content"` | Whether input is raw content or a file path                 |
+| `baseFilePath`         | `string`              | -           | Base file path for reference resolution                     |
+| `allowedRootDirectory` | `string`              | -           | Root directory for file operations (required for file mode) |
+| `timeoutMs`            | `number`              | `15000`     | Operation timeout in milliseconds                           |
+| `maxInputBytes`        | `number`              | `5242880`   | Maximum input size in bytes                                 |
+| `maxDocumentNodes`     | `number`              | `100000`    | Maximum nodes in parsed document                            |
+| `maxDocumentDepth`     | `number`              | `100`       | Maximum nesting depth                                       |
 
-# Watch mode
-npx vitest watch
-```
+---
+
+## Error Codes
+
+| Code                     | Description                                     |
+| ------------------------ | ----------------------------------------------- |
+| `INVALID_OPTION`         | Invalid option value provided                   |
+| `FILE_INPUT_FORBIDDEN`   | File input requires `allowedRootDirectory`      |
+| `PATH_OUTSIDE_ROOT`      | File path is outside the allowed root directory |
+| `INPUT_TOO_LARGE`        | Input exceeds maximum allowed size              |
+| `INPUT_FILE_TOO_LARGE`   | File exceeds maximum allowed size               |
+| `PARSE_ERROR`            | Failed to parse the document                    |
+| `INVALID_DOCUMENT_SHAPE` | Document is not a valid JSON object             |
+| `UNSUPPORTED_VERSION`    | Unsupported OpenAPI/Swagger version             |
+| `DOCUMENT_TOO_LARGE`     | Document exceeds maximum node count             |
+| `DOCUMENT_TOO_DEEP`      | Document exceeds maximum nesting depth          |
+| `SPEC_VALIDATION_FAILED` | OpenAPI validation failed                       |
+| `OPERATION_TIMEOUT`      | Operation timed out                             |
+| `OPERATION_ABORTED`      | Operation was aborted                           |
+| `UNKNOWN_ERROR`          | Unknown error occurred                          |
 
 ---
 
-## Related Packages
+## TypeScript Types
 
-- [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
-- [`@powerduck/openapi-request`](https://www.npmjs.com/package/@powerduck/openapi-request) — Execute OpenAPI operations with full parameter serialization
-- [`@powerduck/openapi-codegen`](https://www.npmjs.com/package/@powerduck/openapi-codegen) — Generate runnable request examples in 21 languages
+```typescript
+import type {
+  PatchOperation,
+  ConfigFormat,
+  ValidateOpenApiOptions,
+  OpenApiValidationError,
+  AnyOpenAPIDocument,
+} from "@powerduck/conf-patch";
+```
 
 ---
 
 ## License
 
-MIT
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/conf-patch",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Two-layer configuration editor: pure core for patching JSON/JSONC/YAML strings (browser-safe), plus file layer with atomic writes and locking for Node.js/Electron. RFC 6902 JSON Patch, comment and formatting preservation, OpenAPI validation.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",