@wgtechlabs/config-engine 0.1.0-staging.d0d9e7f

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waren Gonzaga, WG Technology Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# @wgtechlabs/config-engine
+
+![GitHub Repo Banner](https://ghrb.waren.build/banner?header=config-engine+%F0%9F%8E%9B%EF%B8%8F%F0%9F%9A%82&subheader=configs+should+be+easy&bg=016EEA&color=FFFFFF&headerfont=Google+Sans+Code&subheaderfont=Inter&watermarkpos=bottom-right)
+<!-- Created with GitHub Repo Banner by Waren Gonzaga: https://ghrb.waren.build -->
+
+> Configs should be easy.
+
+Fast, Bun-first configuration SDK for AI agent frameworks, CLI apps, and applications — backed by SQLite with in-memory caching, Zod validation, and optional encryption.
+
+## Use Cases
+
+- **AI agent frameworks** — persistent agent settings, model preferences, API key management, and runtime configuration
+- **CLI applications** — user preferences, saved credentials, and tool configuration that persists across sessions
+- **Desktop & server apps** — application settings with schema validation, safe migrations, and multi-process access
+
+## Features
+
+- **SQLite-backed** — ACID transactions, WAL mode, multi-process safe
+- **In-memory cache** — zero disk I/O on reads, configurable write-behind flush
+- **Zod validation** — built-in schema validation with pluggable validator interface
+- **Dot-notation access** — `config.get("ui.sidebar.width")` just works
+- **Async migrations** — version-based with full transaction rollback on failure
+- **Optional encryption** — AES-256-GCM via [`@wgtechlabs/secrets-engine`](https://github.com/wgtechlabs/secrets-engine) or bring your own
+- **Change events** — watch specific keys or the entire store
+- **Bun-first, Node.js compatible** — uses `bun:sqlite` natively, `better-sqlite3` on Node.js
+
+## Install
+
+```bash
+bun add @wgtechlabs/config-engine
+```
+
+For Node.js, also install the SQLite driver:
+
+```bash
+npm install @wgtechlabs/config-engine better-sqlite3
+```
+
+## Quick Start
+
+```typescript
+import { ConfigEngine } from "@wgtechlabs/config-engine";
+
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  defaults: {
+    theme: "dark",
+    fontSize: 14,
+    sidebar: { width: 300, visible: true },
+  },
+});
+
+// Read (zero disk I/O — reads from in-memory cache)
+config.get("theme");          // "dark"
+config.get("sidebar.width");  // 300 (dot-notation)
+
+// Write
+config.set("fontSize", 16);
+config.set({ theme: "light", fontSize: 12 });
+config.set("sidebar.visible", false);
+
+// Check & delete
+config.has("theme");    // true
+config.delete("theme");
+
+// Iterate
+for (const [key, value] of config) {
+  console.log(key, value);
+}
+
+// Close when done
+config.close();
+```
+
+## Validation with Zod
+
+```typescript
+import { ConfigEngine } from "@wgtechlabs/config-engine";
+import { z } from "zod";
+
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  defaults: { theme: "dark", fontSize: 14 },
+  schema: z.object({
+    theme: z.enum(["light", "dark"]),
+    fontSize: z.number().min(8).max(72),
+  }),
+});
+
+config.set("fontSize", 16);  // OK
+config.set("fontSize", 200); // Throws ValidationError
+```
+
+### Custom Validator (Pluggable)
+
+Bring your own validation library (Valibot, AJV, etc.):
+
+```typescript
+import { ConfigEngine, type Validator } from "@wgtechlabs/config-engine";
+
+const myValidator: Validator<MyConfig> = {
+  validate(data) {
+    // Your validation logic
+    if (isValid(data)) {
+      return { success: true, data: data as MyConfig };
+    }
+    return { success: false, errors: ["Validation failed"] };
+  },
+};
+
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  validator: myValidator,
+});
+```
+
+## Migrations
+
+Robust, async-capable migration system with full SQLite transaction rollback:
+
+```typescript
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  projectVersion: "3.0.0",
+  migrations: [
+    {
+      version: "2.0.0",
+      up(ctx) {
+        // Rename a key
+        const old = ctx.get("oldSetting");
+        if (old !== undefined) {
+          ctx.set("newSetting", old);
+          ctx.delete("oldSetting");
+        }
+      },
+    },
+    {
+      version: "3.0.0",
+      async up(ctx) {
+        // Async migrations supported natively
+        const data = ctx.get<string>("rawData");
+        if (data) {
+          ctx.set("processedData", data.toUpperCase());
+          ctx.delete("rawData");
+        }
+      },
+    },
+  ],
+  beforeEachMigration({ fromVersion, toVersion }) {
+    console.log(`Migrating ${fromVersion} → ${toVersion}`);
+  },
+});
+```
+
+If any migration throws, **all changes are rolled back** automatically.
+
+## Encryption
+
+Optional encryption using [`@wgtechlabs/secrets-engine`](https://github.com/wgtechlabs/secrets-engine) for machine-bound key management:
+
+```bash
+bun add @wgtechlabs/secrets-engine
+```
+
+```typescript
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  encryptionKey: "my-app.config.key", // Key name in secrets-engine
+});
+
+// All values are AES-256-GCM encrypted at rest
+config.set("apiToken", "sk-secret-value");
+```
+
+Or bring your own encryptor:
+
+```typescript
+import { ConfigEngine, type Encryptor } from "@wgtechlabs/config-engine";
+
+const myEncryptor: Encryptor = {
+  async encrypt(plaintext) { /* ... */ },
+  async decrypt(ciphertext) { /* ... */ },
+};
+
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  encryptionKey: myEncryptor,
+});
+```
+
+## Change Events
+
+```typescript
+// Watch a specific key
+const unsubscribe = config.onDidChange("theme", (newValue, oldValue) => {
+  console.log(`Theme changed: ${oldValue} → ${newValue}`);
+});
+
+// Watch any change
+config.onDidAnyChange((newStore, oldStore) => {
+  console.log("Config updated");
+});
+
+// Stop watching
+unsubscribe();
+```
+
+## Flush Strategies
+
+Control when writes hit disk:
+
+```typescript
+// Immediate — sync write on every .set() (safest)
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  flushStrategy: "immediate",
+});
+
+// Batched — debounced microtask flush (default, best perf)
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  flushStrategy: "batched",
+});
+
+// Manual — you control when to flush
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  flushStrategy: "manual",
+});
+config.set("key", "value");
+await config.flush(); // Explicit flush
+```
+
+## Where Config is Stored
+
+SQLite database files are stored in platform-appropriate directories:
+
+| OS | Default Path |
+|---|---|
+| macOS | `~/Library/Preferences/<projectName>/config.db` |
+| Windows | `%APPDATA%/<projectName>/config.db` |
+| Linux | `~/.config/<projectName>/config.db` |
+
+Override with `cwd`:
+
+```typescript
+const config = await ConfigEngine.open({
+  projectName: "my-app",
+  cwd: "/custom/path",  // → /custom/path/config.db
+});
+```
+
+## API Reference
+
+### `ConfigEngine.open(options)`
+
+Async factory method. Returns `Promise<ConfigEngine<T>>`.
+
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `projectName` | `string` | **required** | App identifier for path resolution |
+| `projectVersion` | `string` | — | Required when `migrations` is set |
+| `cwd` | `string` | OS config dir | Override config directory |
+| `configName` | `string` | `"config"` | Database file name (without `.db`) |
+| `defaults` | `Partial<T>` | — | Default values, merged on first open |
+| `schema` | `ZodSchema<T>` | — | Zod schema for validation |
+| `validator` | `Validator<T>` | — | Custom validator (overrides `schema`) |
+| `encryptionKey` | `string \| Encryptor` | — | Encryption key name or custom encryptor |
+| `migrations` | `MigrationDefinition[]` | — | Ordered migration definitions |
+| `beforeEachMigration` | `Function` | — | Hook before each migration |
+| `afterEachMigration` | `Function` | — | Hook after each migration |
+| `flushStrategy` | `FlushStrategy` | `"batched"` | Write-behind strategy |
+| `accessPropertiesByDotNotation` | `boolean` | `true` | Enable dot-notation access |
+| `watch` | `boolean` | `false` | Watch for external changes |
+| `clearInvalidConfig` | `boolean` | `false` | Clear store on validation/decrypt failure |
+
+### Instance Methods
+
+| Method | Description |
+|---|---|
+| `.get(key, defaultValue?)` | Get a value (dot-notation supported) |
+| `.set(key, value)` | Set a single value |
+| `.set(object)` | Set multiple values |
+| `.has(key)` | Check if a key exists |
+| `.delete(key)` | Remove a key |
+| `.clear()` | Clear all values, restore defaults |
+| `.reset(...keys)` | Reset specific keys to defaults |
+| `.onDidChange(key, cb)` | Watch a key, returns unsubscribe |
+| `.onDidAnyChange(cb)` | Watch all changes, returns unsubscribe |
+| `.flush()` | Flush pending writes (async) |
+| `.flushSync()` | Flush pending writes (sync) |
+| `.close()` | Close the engine |
+
+### Instance Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `.store` | `T` | Get/set the entire config object |
+| `.size` | `number` | Number of top-level entries |
+| `.path` | `string` | Absolute path to the database file |
+
+## License
+
+MIT © [WGTech Labs](https://github.com/wgtechlabs)

package/dist/cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module cache
+ * In-memory cache with configurable write-behind strategy.
+ * All `.get()` calls hit the Map (zero disk I/O). Writes are
+ * flushed to the SQLite store based on the configured strategy.
+ */
+import type { ConfigStore } from "./store.js";
+import type { FlushStrategy } from "./types.js";
+export declare class ConfigCache<T extends Record<string, unknown>> {
+    #private;
+    constructor(store: ConfigStore, strategy?: FlushStrategy);
+    /** Load all data from the store into memory. */
+    load(initial?: Record<string, unknown>): void;
+    get(key: string): unknown;
+    has(key: string): boolean;
+    get size(): number;
+    /** Return a shallow copy of the entire store as a plain object. */
+    getAll(): T;
+    entries(): IterableIterator<[string, unknown]>;
+    set(key: string, value: unknown): void;
+    setMany(entries: Array<[string, unknown]>): void;
+    delete(key: string): boolean;
+    clear(): void;
+    /** Replace the entire in-memory store and schedule a full flush. */
+    replaceAll(data: T): void;
+    /** Synchronously flush all pending changes to SQLite. */
+    flushSync(): void;
+    /**
+     * Wait for any pending batched flush to complete.
+     * Returns immediately if no flush is pending.
+     */
+    flush(): Promise<void>;
+    /** Reload from disk, discarding uncommitted changes. */
+    reload(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qBAAa,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;gBAS7C,KAAK,EAAE,WAAW,EAAE,QAAQ,GAAE,aAAyB;IAKnE,gDAAgD;IAChD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAe7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mEAAmE;IACnE,MAAM,IAAI,CAAC;IAQX,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAQ9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAOtC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI;IAShD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAU5B,KAAK,IAAI,IAAI;IAUb,oEAAoE;IACpE,UAAU,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAyCzB,yDAAyD;IACzD,SAAS,IAAI,IAAI;IAyBjB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,wDAAwD;IACxD,MAAM,IAAI,IAAI;CAKd"}

package/dist/chunk-gs6j6hrj.js

@@ -0,0 +1,35 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/validation.ts
+function createZodValidator(schema) {
+  return {
+    validate(data) {
+      const result = schema.safeParse(data);
+      if (result.success) {
+        return { success: true, data: result.data };
+      }
+      return {
+        success: false,
+        errors: formatZodErrors(result.error)
+      };
+    }
+  };
+}
+function formatZodErrors(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `\`${issue.path.join(".")}\` ` : "";
+    return `${path}${issue.message}`;
+  });
+}
+function resolveValidator(options) {
+  if (options.validator)
+    return options.validator;
+  if (options.schema)
+    return createZodValidator(options.schema);
+  return;
+}
+
+export { __require, createZodValidator, resolveValidator };
+
+//# debugId=7925FF196403AB3864756E2164756E21

package/dist/chunk-gs6j6hrj.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/validation.ts"],
+  "sourcesContent": [
+    "/**\n * @module validation\n * Pluggable validation system with built-in Zod adapter.\n */\n\nimport { type ZodSchema, type ZodError } from \"zod\";\nimport type { ValidationResult, Validator } from \"./types.js\";\n\n/**\n * Create a `Validator<T>` backed by a Zod schema.\n *\n * ```ts\n * import { z } from \"zod\";\n * import { createZodValidator } from \"@wgtechlabs/config-engine/validators/zod\";\n *\n * const validator = createZodValidator(z.object({\n *   theme: z.enum([\"light\", \"dark\"]),\n *   fontSize: z.number().min(8).max(72),\n * }));\n * ```\n */\nexport function createZodValidator<T>(schema: ZodSchema<T>): Validator<T> {\n\treturn {\n\t\tvalidate(data: unknown): ValidationResult<T> {\n\t\t\tconst result = schema.safeParse(data);\n\t\t\tif (result.success) {\n\t\t\t\treturn { success: true, data: result.data };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tsuccess: false,\n\t\t\t\terrors: formatZodErrors(result.error),\n\t\t\t};\n\t\t},\n\t};\n}\n\n/**\n * Format Zod errors into human-readable strings.\n */\nfunction formatZodErrors(error: ZodError): string[] {\n\treturn error.issues.map((issue) => {\n\t\tconst path = issue.path.length > 0 ? `\\`${issue.path.join(\".\")}\\` ` : \"\";\n\t\treturn `${path}${issue.message}`;\n\t});\n}\n\n/**\n * Build a validator from the options — resolves `schema` vs `validator`.\n */\nexport function resolveValidator<T>(options: {\n\tschema?: ZodSchema<T>;\n\tvalidator?: Validator<T>;\n}): Validator<T> | undefined {\n\t// Explicit validator takes precedence\n\tif (options.validator) return options.validator;\n\t// Fall back to Zod schema\n\tif (options.schema) return createZodValidator(options.schema);\n\treturn undefined;\n}\n"
+  ],
+  "mappings": ";;;;AAqBO,SAAS,kBAAqB,CAAC,QAAoC;AAAA,EACzE,OAAO;AAAA,IACN,QAAQ,CAAC,MAAoC;AAAA,MAC5C,MAAM,SAAS,OAAO,UAAU,IAAI;AAAA,MACpC,IAAI,OAAO,SAAS;AAAA,QACnB,OAAO,EAAE,SAAS,MAAM,MAAM,OAAO,KAAK;AAAA,MAC3C;AAAA,MACA,OAAO;AAAA,QACN,SAAS;AAAA,QACT,QAAQ,gBAAgB,OAAO,KAAK;AAAA,MACrC;AAAA;AAAA,EAEF;AAAA;AAMD,SAAS,eAAe,CAAC,OAA2B;AAAA,EACnD,OAAO,MAAM,OAAO,IAAI,CAAC,UAAU;AAAA,IAClC,MAAM,OAAO,MAAM,KAAK,SAAS,IAAI,KAAK,MAAM,KAAK,KAAK,GAAG,SAAS;AAAA,IACtE,OAAO,GAAG,OAAO,MAAM;AAAA,GACvB;AAAA;AAMK,SAAS,gBAAmB,CAAC,SAGP;AAAA,EAE5B,IAAI,QAAQ;AAAA,IAAW,OAAO,QAAQ;AAAA,EAEtC,IAAI,QAAQ;AAAA,IAAQ,OAAO,mBAAmB,QAAQ,MAAM;AAAA,EAC5D;AAAA;",
+  "debugId": "7925FF196403AB3864756E2164756E21",
+  "names": []
+}

package/dist/dot-prop.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module dot-prop
+ * Lightweight dot-notation property access utilities.
+ * Zero dependencies — replaces the `dot-prop` npm package.
+ */
+/**
+ * Get a nested value using dot-notation path.
+ *
+ * ```ts
+ * getByPath({ a: { b: { c: 42 } } }, "a.b.c") // 42
+ * getByPath({ a: { b: 1 } }, "a.x")            // undefined
+ * ```
+ */
+export declare function getByPath(obj: unknown, path: string): unknown;
+/**
+ * Set a nested value using dot-notation path. Creates intermediate
+ * objects as needed. Returns a new object (shallow copies along the path).
+ *
+ * ```ts
+ * setByPath({}, "a.b.c", 42)            // { a: { b: { c: 42 } } }
+ * setByPath({ a: { x: 1 } }, "a.b", 2) // { a: { x: 1, b: 2 } }
+ * ```
+ */
+export declare function setByPath<T extends Record<string, unknown>>(obj: T, path: string, value: unknown): T;
+/**
+ * Check if a nested path exists.
+ */
+export declare function hasByPath(obj: unknown, path: string): boolean;
+/**
+ * Delete a nested property using dot-notation path.
+ * Returns a new object (shallow copies along the path).
+ * Returns the original object if the path doesn't exist.
+ */
+export declare function deleteByPath<T extends Record<string, unknown>>(obj: T, path: string): T;
+//# sourceMappingURL=dot-prop.d.ts.map

package/dist/dot-prop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot-prop.d.ts","sourceRoot":"","sources":["../src/dot-prop.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAY7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACZ,CAAC,CAsBH;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAc7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,GACV,CAAC,CAqBH"}

package/dist/encryption.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module encryption
+ * Optional encryption integration via `@wgtechlabs/secrets-engine`.
+ * Also supports custom `Encryptor` implementations.
+ */
+import type { Encryptor } from "./types.js";
+/**
+ * Encryption adapter that uses `@wgtechlabs/secrets-engine`.
+ *
+ * The encryption key is stored securely in secrets-engine (machine-bound,
+ * AES-256-GCM). This adapter retrieves the key on init and uses it to
+ * encrypt/decrypt config values via Node's `crypto` module.
+ */
+export declare class SecretsEngineEncryptor implements Encryptor {
+    #private;
+    constructor(keyName: string);
+    /** Initialize the encryptor — must be called before encrypt/decrypt. */
+    init(): Promise<void>;
+    encrypt(plaintext: string): Promise<string>;
+    decrypt(ciphertext: string): Promise<string>;
+    /** Close the underlying secrets-engine instance. */
+    close(): Promise<void>;
+}
+/**
+ * Resolve the encryptor from options.
+ * - If a string key name is provided, create a `SecretsEngineEncryptor`.
+ * - If an `Encryptor` object is provided, use it directly.
+ * - If undefined, return undefined (no encryption).
+ */
+export declare function resolveEncryptor(encryptionKey?: string | Encryptor): Promise<Encryptor | undefined>;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,SAAS;;gBAM3C,OAAO,EAAE,MAAM;IAI3B,wEAAwE;IAClE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCrB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB3C,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBlD,oDAAoD;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM5B;AAsCD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACrC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,GAChC,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAWhC"}

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @module config-engine
+ * Fast, Bun-first configuration engine with SQLite-backed storage.
+ *
+ * @example
+ * ```ts
+ * import { ConfigEngine } from "@wgtechlabs/config-engine";
+ * import { z } from "zod";
+ *
+ * const config = await ConfigEngine.open({
+ *   projectName: "my-app",
+ *   defaults: { theme: "dark", fontSize: 14 },
+ *   schema: z.object({
+ *     theme: z.enum(["light", "dark"]),
+ *     fontSize: z.number().min(8).max(72),
+ *   }),
+ * });
+ *
+ * config.get("theme");        // "dark"
+ * config.set("fontSize", 16);
+ * config.set({ theme: "light", fontSize: 12 });
+ *
+ * config.close();
+ * ```
+ */
+import type { AnyChangeCallback, ChangeCallback, ConfigEngineOptions, Unsubscribe } from "./types.js";
+export type { ConfigEngineOptions, Validator, ValidationResult, ValidationSuccess, ValidationFailure, Encryptor, MigrationDefinition, MigrationContext, MigrationHookContext, FlushStrategy as FlushStrategyType, ChangeCallback, AnyChangeCallback, Unsubscribe, } from "./types.js";
+export { createZodValidator, resolveValidator } from "./validation.js";
+export { resolveConfigDir, resolveConfigPath } from "./platform.js";
+export type { FlushStrategy } from "./types.js";
+export declare class ConfigEngineError extends Error {
+    name: string;
+}
+export declare class ValidationError extends ConfigEngineError {
+    name: string;
+    errors: string[];
+    constructor(errors: string[]);
+}
+export declare class ConfigEngine<T extends Record<string, unknown>> {
+    #private;
+    /**
+     * Private constructor — use `ConfigEngine.open()` instead.
+     */
+    private constructor();
+    /**
+     * Async factory — the only way to create a `ConfigEngine` instance.
+     * Handles encryption init, migration, and initial validation.
+     */
+    static open<T extends Record<string, unknown>>(options: ConfigEngineOptions<T>): Promise<ConfigEngine<T>>;
+    /**
+     * Get a config value by key. Supports dot-notation by default.
+     * @param key - The configuration key.
+     * @param defaultValue - Fallback value if the key doesn't exist.
+     */
+    get<K extends string & keyof T>(key: K): T[K] | undefined;
+    get<K extends string & keyof T>(key: K, defaultValue: T[K]): T[K];
+    get<V = unknown>(key: string, defaultValue?: V): V | undefined;
+    /**
+     * Check whether a key exists in the config.
+     */
+    has(key: string): boolean;
+    /**
+     * Get the entire config store as a typed object (shallow copy).
+     */
+    get store(): T;
+    /**
+     * Replace the entire config store.
+     */
+    set store(value: T);
+    /**
+     * Number of top-level config entries.
+     */
+    get size(): number;
+    /**
+     * Absolute path to the SQLite database file.
+     */
+    get path(): string;
+    /**
+     * Set a config value. Supports two signatures:
+     * - `set(key, value)` — set a single key
+     * - `set(object)` — set multiple keys at once
+     */
+    set<K extends string & keyof T>(key: K, value: T[K]): void;
+    set(key: string, value: unknown): void;
+    set(object: Partial<T>): void;
+    /**
+     * Delete a config key.
+     */
+    delete(key: string): void;
+    /**
+     * Delete all config entries and restore defaults.
+     */
+    clear(): void;
+    /**
+     * Reset specific keys to their default values.
+     */
+    reset(...keys: (string & keyof T)[]): void;
+    /**
+     * Watch a specific key for changes.
+     * @returns An unsubscribe function.
+     */
+    onDidChange<K extends string & keyof T>(key: K, callback: ChangeCallback<T[K]>): Unsubscribe;
+    /**
+     * Watch the entire store for any change.
+     * @returns An unsubscribe function.
+     */
+    onDidAnyChange(callback: AnyChangeCallback<T>): Unsubscribe;
+    /**
+     * Flush any pending writes to disk.
+     * Required when using `flushStrategy: "manual"`.
+     */
+    flush(): Promise<void>;
+    /**
+     * Synchronously flush any pending writes to disk.
+     */
+    flushSync(): void;
+    /**
+     * Close the config engine. Flushes pending writes and releases
+     * the database connection. The instance cannot be used after closing.
+     */
+    close(): void;
+    [Symbol.iterator](): IterableIterator<[string, unknown]>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}