@effected/config-file 0.1.0

package/index.js

@@ -0,0 +1,14 @@
+import { ConfigCodecError } from "./ConfigCodec.js";
+import { ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigSourceRef } from "./ConfigEvent.js";
+import { ConfigResolver } from "./ConfigResolver.js";
+import { ConfigDefaultPathMissingError, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigValidationError } from "./ConfigFile.js";
+import { ConfigMigration, ConfigMigrationError, VersionAccess } from "./ConfigMigration.js";
+import { asConfigProvider, layerConfigProvider } from "./ConfigProvider.js";
+import { ConfigEncryptionError, EncryptedCodec, EncryptedCodecKey } from "./EncryptedCodec.js";
+import { JsonCodec } from "./JsonCodec.js";
+import { JsoncCodec } from "./JsoncCodec.js";
+import { MergeStrategy } from "./MergeStrategy.js";
+import { TomlCodec } from "./TomlCodec.js";
+import { YamlCodec } from "./YamlCodec.js";
+
+export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, JsoncCodec, MergeStrategy, TomlCodec, VersionAccess, YamlCodec, asConfigProvider, layerConfigProvider };

package/internal/crypto.js

@@ -0,0 +1,115 @@
+import { Effect } from "effect";
+
+//#region src/internal/crypto.ts
+/**
+* AES-GCM primitives over WebCrypto.
+*
+* @remarks
+* This module imports nothing from the rest of the package. `EncryptedCodec.ts`
+* imports these helpers, so a back-import of `ConfigEncryptionError` would close
+* a cycle that Biome's error-level `noImportCycles` rule rejects. Staying
+* dependency-free also keeps the module cheap to extract later.
+*
+* Failures surface as the plain {@link CryptoFailure} record; the public module
+* lifts them into `ConfigEncryptionError`.
+*
+* @internal
+*/
+/** AES-GCM's standard IV length, in bytes. @internal */
+const IV_LENGTH = 12;
+/** Tag a caught host failure with the phase that produced it, preserving it by identity. */
+const fail = (phase) => (cause) => ({
+	phase,
+	cause
+});
+/**
+* Copy a `Uint8Array` into a fresh `Uint8Array` backed by a plain `ArrayBuffer`,
+* which is required by Web Crypto APIs that accept `BufferSource`.
+*
+* @internal
+*/
+function toArrayBufferView(src) {
+	const buf = new ArrayBuffer(src.length);
+	const view = new Uint8Array(buf);
+	view.set(src);
+	return view;
+}
+/**
+* Derive an AES-GCM key from a passphrase via PBKDF2.
+*
+* @remarks
+* The caller memoizes this so PBKDF2 runs once per codec instance.
+*
+* @internal
+*/
+const deriveKey = (passphrase, salt) => Effect.tryPromise({
+	try: async () => {
+		const enc = new TextEncoder();
+		const keyMaterial = await globalThis.crypto.subtle.importKey("raw", enc.encode(passphrase), "PBKDF2", false, ["deriveKey"]);
+		return await globalThis.crypto.subtle.deriveKey({
+			name: "PBKDF2",
+			salt: toArrayBufferView(salt),
+			iterations: 6e5,
+			hash: "SHA-256"
+		}, keyMaterial, {
+			name: "AES-GCM",
+			length: 256
+		}, false, ["encrypt", "decrypt"]);
+	},
+	catch: fail("key-derivation")
+});
+/**
+* Decode base64 into bytes.
+*
+* @remarks
+* `atob` is available in all modern environments (Node 20+, Bun, Deno).
+*
+* @internal
+*/
+const fromBase64 = (raw) => Effect.try({
+	try: () => {
+		const binary = atob(raw);
+		const buf = new ArrayBuffer(binary.length);
+		const bytes = new Uint8Array(buf);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	},
+	catch: fail("encoding")
+});
+/**
+* Prepend the IV to the ciphertext and base64-encode the envelope.
+*
+* @internal
+*/
+const toBase64 = (iv, ciphertext) => Effect.try({
+	try: () => {
+		const ciphertextBytes = new Uint8Array(ciphertext);
+		const resultBuf = new ArrayBuffer(12 + ciphertextBytes.length);
+		const result = new Uint8Array(resultBuf);
+		result.set(iv, 0);
+		result.set(ciphertextBytes, 12);
+		return btoa(Array.from(result, (b) => String.fromCharCode(b)).join(""));
+	},
+	catch: fail("encoding")
+});
+/** Decrypt AES-GCM ciphertext under `iv`. @internal */
+const decrypt = (key, iv, ciphertext) => Effect.tryPromise({
+	try: () => globalThis.crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv
+	}, key, ciphertext),
+	catch: fail("decrypt")
+});
+/** Encrypt `plaintext` with AES-GCM under `iv`. @internal */
+const encrypt = (key, iv, plaintext) => Effect.tryPromise({
+	try: () => globalThis.crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, key, plaintext),
+	catch: fail("encrypt")
+});
+/** A fresh cryptographically random 12-byte IV. @internal */
+const randomIv = () => globalThis.crypto.getRandomValues(new Uint8Array(/* @__PURE__ */ new ArrayBuffer(12)));
+
+//#endregion
+export { decrypt, deriveKey, encrypt, fromBase64, randomIv, toArrayBufferView, toBase64 };

package/internal/deepMerge.js

@@ -0,0 +1,80 @@
+//#region src/internal/deepMerge.ts
+/**
+* A true plain object: `{}` or `Object.create(null)`. Class instances, `Date`,
+* `Map`, `Set`, `RegExp` and arrays are values, not merge targets.
+*
+* @remarks
+* This is deliberately narrower than `typeof v === "object"`. A `Date` spread
+* into a fresh object loses every internal slot and yields `{}`; a class
+* instance loses its prototype, so `instanceof` fails and its getters vanish.
+* Recursion is gated on this predicate so nested values of those kinds stay
+* atomic — the higher-priority source wins them whole.
+*/
+const isPlainObject = (value) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+/**
+* Record-like: a `[object Object]` whose fields can be merged. Admits plain
+* objects and class instances (a decoded `Schema.Class` document), but not
+* `Date` / `Map` / `Set` / `RegExp` / arrays, whose behaviour lives in internal
+* slots that a field-wise merge would destroy.
+*/
+const isRecordLike = (value) => typeof value === "object" && value !== null && Object.prototype.toString.call(value) === "[object Object]";
+/**
+* Two values may be merged only if both are record-like and share a prototype.
+* Same-prototype instances merge field-wise; anything else is atomic.
+*
+* @remarks
+* Requiring an identical prototype is what keeps the merge honest: a document
+* decoded through `Schema.Class` merges with another of the same class and
+* keeps its identity, and nothing else is ever silently reshaped.
+*/
+const canMerge = (a, b) => isRecordLike(a) && isRecordLike(b) && Object.getPrototypeOf(a) === Object.getPrototypeOf(b);
+const FORBIDDEN = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Recursively merge `source` into `target`; keys already present on `target`
+* win. Nested plain objects merge; every other value is atomic.
+*
+* @remarks
+* The result is built on `target`'s prototype rather than spread into `{}`, so
+* a decoded `Schema.Class` document survives the merge as a real instance —
+* `instanceof` holds and its getters still work. Without this, `load` would
+* declare `Effect<A>` and hand back a structurally-equal plain object, and a
+* consumer calling a class method would get a `TypeError` that typechecked.
+*
+* Only own enumerable keys are consulted (`Object.hasOwn`), so a prototype
+* getter on `target` never shadows a real key on `source`.
+*/
+const deepMerge = (target, source) => {
+	const result = Object.create(Object.getPrototypeOf(target));
+	for (const key of Object.keys(target)) {
+		if (FORBIDDEN.has(key)) continue;
+		define(result, key, target[key]);
+	}
+	for (const key of Object.keys(source)) {
+		if (FORBIDDEN.has(key)) continue;
+		const sourceValue = source[key];
+		const targetValue = result[key];
+		if (Object.hasOwn(result, key) && isPlainObject(targetValue) && isPlainObject(sourceValue)) define(result, key, deepMerge(targetValue, sourceValue));
+		else if (!Object.hasOwn(result, key)) define(result, key, sourceValue);
+	}
+	return result;
+};
+/** Create an own data property, never invoking a setter inherited from the prototype chain. */
+const define = (target, key, value) => {
+	Object.defineProperty(target, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+};
+
+//#endregion
+export { canMerge, deepMerge, isPlainObject };

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@effected/config-file",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
+	"keywords": [
+		"config",
+		"config-file",
+		"codec",
+		"json",
+		"jsonc",
+		"yaml",
+		"toml",
+		"resolver",
+		"merge-strategy",
+		"effect",
+		"schema",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/config-file#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/config-file"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/jsonc": "0.1.0",
+		"@effected/toml": "0.1.0",
+		"@effected/walker": "0.1.0",
+		"@effected/yaml": "0.1.0",
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}