@effected/package-json 0.2.0 → 0.3.1

package/Package.js

@@ -1,7 +1,7 @@
 import { Dependency } from "./Dependency.js";
 import { DevEnginesSchema } from "./DevEngines.js";
 import { InvalidSpdxLicenseError, SpdxLicense, isValidSpdx } from "./License.js";
-import { renderJson } from "./internal/format.js";
+import { renderJson, resolveIndent } from "./internal/format.js";
 import { PackageManager } from "./PackageManager.js";
 import { InvalidPackageNameError, PackageName } from "./PackageName.js";
 import { Person } from "./Person.js";
@@ -84,7 +84,7 @@ cause: Schema.Defect() }) {
 	}
 };
 const resolveFormatOptions = (options) => ({
-	indent: options?.indent ?? 2,
+	indent: resolveIndent(options?.indent, options?.sourceText),
 	sort: options?.sort ?? true,
 	stripEmpty: options?.stripEmpty ?? true,
 	newline: options?.newline ?? true

package/PackageJsonFile.js

@@ -104,7 +104,15 @@ var PackageJsonFile = class PackageJsonFile extends Context.Service()("@effected
 				return yield* Package.decode(json);
 			}),
 			write: Effect.fn("PackageJsonFile.write")(function* (target, pkg, options) {
-				const json = pkg.toJsonString(options);
+				let effective = options;
+				if (options?.indent === "preserve" && options.sourceText === void 0) {
+					const existing = yield* fs.readFileString(target).pipe(Effect.catch(() => Effect.succeed(void 0)));
+					if (existing !== void 0) effective = {
+						...options,
+						sourceText: existing
+					};
+				}
+				const json = pkg.toJsonString(effective);
 				const directory = path.dirname(target);
 				yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError((cause) => new PackageJsonWriteError({
 					path: target,

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@effected%2Fpackage-json?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/package-json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
-[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
 package.json parsing, editing, validation and file IO as Effect schemas. `Package` is a `Schema.Class` with the manifest's known fields typed — `name` is a branded npm name, `version` is a real `SemVer`, `packageManager` decodes into `{ name, version, integrity }` — and a `rest` catch-all that carries every unknown top-level key through a read, edit and write cycle without losing it. Editing is immutable and dual-signature, validation is a rule set you can replace, and `catalog:` / `workspace:` specifiers expand through the `@effected/npm` resolver contracts as an explicit step you opt into.
 
@@ -37,6 +37,8 @@ pnpm add @effected/package-json effect @effect/platform-node
 
 Requires Node.js >=24.11.0.
 
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
 `effect` v4 is the only peer dependency. `@effected/semver` and `@effected/npm` come along as ordinary dependencies — they back the `version` field and the resolver contracts — and `spdx-expression-parse` is the one external package in the tree, used to validate SPDX license expressions.
 
 Reading and writing files needs a `FileSystem` and a `Path` implementation, provided once at the edge, from `@effect/platform-node` on Node. Everything except `PackageJsonFile` is pure and needs no platform layer at all.

package/index.d.ts

@@ -327,14 +327,31 @@ declare const PackageDecodeError_base: Schema.Class<PackageDecodeError, Schema.T
 declare class PackageDecodeError extends PackageDecodeError_base {
   get message(): string;
 }
+/**
+ * Indentation for serialized package.json output: a spaces count, `"tab"` for
+ * real tab indentation, or `"preserve"` to reuse the indentation detected from
+ * the original source text (falling back to the two-space default when no
+ * source text is available).
+ *
+ * @public
+ */
+type PackageIndent = number | "tab" | "preserve";
 /**
  * Options for {@link Package.toJsonString} and `PackageJsonFile.write`.
  *
  * @public
  */
 interface PackageFormatOptions {
-  /** Indentation width in spaces (default `2`). */
-  readonly indent?: number;
+  /** Indentation: a spaces count, `"tab"`, or `"preserve"` (default `2`). */
+  readonly indent?: PackageIndent;
+  /**
+   * The original source text backing `indent: "preserve"`: its indentation
+   * (tab vs N spaces, detected from the first indented line) is reused.
+   * Ignored for other `indent` values. When absent, `PackageJsonFile.write`
+   * supplies the existing file's text automatically; the pure
+   * {@link Package.toJsonString} falls back to the default indentation.
+   */
+  readonly sourceText?: string;
   /** Order top-level keys canonically and alphabetize dependency maps (default `true`). */
   readonly sort?: boolean;
   /** Strip empty dependency-map keys (default `true`). */
@@ -622,7 +639,12 @@ interface PackageJsonFileShape {
    * (invalid JSON) or `PackageDecodeError` (schema decode).
    */
   readonly read: (path: string) => Effect.Effect<Package, PackageJsonReadError | PackageJsonNotFoundError | PackageJsonParseError | PackageDecodeError>;
-  /** Serialize and write a package.json file. Fails with `PackageJsonWriteError`. */
+  /**
+   * Serialize and write a package.json file. Fails with
+   * `PackageJsonWriteError`. With `indent: "preserve"` and no explicit
+   * `sourceText`, the existing file at `path` (when readable) supplies the
+   * source text whose indentation is preserved.
+   */
   readonly write: (path: string, pkg: Package, options?: PackageFormatOptions) => Effect.Effect<void, PackageJsonWriteError>;
 }
 declare const PackageJsonFile_base: Context.ServiceClass<PackageJsonFile, "@effected/package-json/PackageJsonFile", PackageJsonFileShape>;
@@ -755,5 +777,5 @@ declare class PackageValidator extends PackageValidator_base {
   }): Layer.Layer<PackageValidator>;
 }
 //#endregion
-export { BinField, Dependency, type DependencyKind, DependencyMapField, type DependencyProtocol, DependencySpecifier, type DependencySpecifierBrand, DevEngine, DevEngineOrArray, type DevEngines, DevEnginesSchema, ExportsField, InvalidDependencySpecifierError, InvalidPackageNameError, InvalidSpdxLicenseError, Package, PackageDecodeError, type PackageFormatOptions, PackageJsonFile, type PackageJsonFileShape, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonWriteError, PackageManager, PackageName, type PackagePatch, PackageValidationError, PackageValidator, PeerDependenciesMetaField, Person, PublishConfigField, RepositoryField, type RuleFailure, ScopedPackageName, SpdxLicense, StringMapField, type UnresolvedDependency, UnscopedPackageName, type ValidationRule, defaultRules, isUnresolvedDependency, isValidDependencySpecifier, isValidSpdx, noLocalDepsRule, noUnresolvedDepsRule };
+export { BinField, Dependency, type DependencyKind, DependencyMapField, type DependencyProtocol, DependencySpecifier, type DependencySpecifierBrand, DevEngine, DevEngineOrArray, type DevEngines, DevEnginesSchema, ExportsField, InvalidDependencySpecifierError, InvalidPackageNameError, InvalidSpdxLicenseError, Package, PackageDecodeError, type PackageFormatOptions, type PackageIndent, PackageJsonFile, type PackageJsonFileShape, PackageJsonNotFoundError, PackageJsonParseError, PackageJsonReadError, PackageJsonWriteError, PackageManager, PackageName, type PackagePatch, PackageValidationError, PackageValidator, PeerDependenciesMetaField, Person, PublishConfigField, RepositoryField, type RuleFailure, ScopedPackageName, SpdxLicense, StringMapField, type UnresolvedDependency, UnscopedPackageName, type ValidationRule, defaultRules, isUnresolvedDependency, isValidDependencySpecifier, isValidSpdx, noLocalDepsRule, noUnresolvedDepsRule };
 //# sourceMappingURL=index.d.ts.map

package/internal/format.js

@@ -2,94 +2,213 @@
 const KEY_INDEX = new Map([
 	"$schema",
 	"name",
+	"displayName",
 	"version",
+	"stableVersion",
 	"private",
 	"description",
+	"categories",
 	"keywords",
 	"homepage",
 	"bugs",
 	"repository",
 	"funding",
 	"license",
+	"qna",
 	"author",
+	"maintainers",
 	"contributors",
+	"publisher",
+	"sideEffects",
 	"type",
 	"imports",
 	"exports",
 	"main",
+	"svelte",
+	"umd:main",
+	"jsdelivr",
+	"unpkg",
 	"module",
+	"source",
+	"jsnext:main",
 	"browser",
+	"react-native",
+	"types",
+	"typesVersions",
+	"typings",
+	"style",
+	"example",
+	"examplestyle",
+	"assets",
 	"bin",
 	"man",
-	"files",
 	"directories",
+	"files",
 	"workspaces",
+	"binary",
 	"scripts",
+	"betterScripts",
+	"wireit",
+	"l10n",
+	"contributes",
+	"activationEvents",
+	"husky",
+	"simple-git-hooks",
+	"pre-commit",
+	"commitlint",
+	"lint-staged",
+	"nano-staged",
 	"config",
+	"nodemonConfig",
+	"browserify",
+	"babel",
+	"browserslist",
+	"xo",
+	"prettier",
+	"eslintConfig",
+	"eslintIgnore",
+	"npmpkgjsonlint",
+	"npmPackageJsonLintConfig",
+	"npmpackagejsonlint",
+	"release",
+	"remarkConfig",
+	"stylelint",
+	"ava",
+	"jest",
+	"jest-junit",
+	"jest-stare",
+	"mocha",
+	"nyc",
+	"c8",
+	"tap",
+	"oclif",
+	"resolutions",
+	"overrides",
 	"dependencies",
 	"devDependencies",
+	"dependenciesMeta",
 	"peerDependencies",
 	"peerDependenciesMeta",
 	"optionalDependencies",
+	"bundledDependencies",
 	"bundleDependencies",
-	"overrides",
+	"extensionPack",
+	"extensionDependencies",
+	"flat",
+	"packageManager",
 	"engines",
+	"engineStrict",
 	"devEngines",
+	"volta",
+	"languageName",
 	"os",
 	"cpu",
+	"preferGlobal",
 	"publishConfig",
-	"packageManager"
+	"icon",
+	"badges",
+	"galleryBanner",
+	"preview",
+	"markdown",
+	"pnpm"
 ].map((k, i) => [k, i]));
 /**
-* Deterministic, locale-independent string comparison by code point. A bare
+* Deterministic, locale-independent string comparison by code unit. A bare
 * `localeCompare` sorts differently across ICU builds/locales; package.json key
 * order must be stable everywhere.
 */
 const byCodePoint = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-const DEPENDENCY_KEYS = /* @__PURE__ */ new Set([
+/**
+* Top-level map fields whose entries are alphabetized when sorting. The
+* dependency maps for canonical presentation; `scripts` / `engines` / `bin`
+* additionally because the `Package` model carries them as `HashMap`s, whose
+* encode order is hash order — source order is already gone, so a deterministic
+* alphabetical order is strictly better. `sort-package-json` sorts `engines`
+* and `bin` identically; its `scripts` sort is a grouped sort that agrees with
+* plain code-unit order except for `pre*`/`post*` script pairing.
+*/
+const SORTED_MAP_KEYS = /* @__PURE__ */ new Set([
 	"dependencies",
 	"devDependencies",
 	"peerDependencies",
 	"optionalDependencies",
-	"bundleDependencies"
+	"bundleDependencies",
+	"scripts",
+	"engines",
+	"bin"
 ]);
-/** Alphabetize the entries of a plain-object dependency map. */
-const sortDependencyMap = (value) => {
+/** Alphabetize the entries of a plain-object map field. */
+const sortMapEntries = (value) => {
 	const result = {};
 	for (const key of Object.keys(value).sort(byCodePoint)) result[key] = value[key];
 	return result;
 };
 const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 /**
-* Order top-level keys canonically (known keys by {@link KEY_ORDER}, the rest
-* alphabetically) and alphabetize dependency-map entries.
+* Order top-level keys canonically (known keys by {@link KEY_ORDER}, then
+* unknown public keys alphabetically, then unknown `_`-prefixed keys
+* alphabetically) and alphabetize the {@link SORTED_MAP_KEYS} map entries.
 */
 const sortKeys = (obj) => {
 	const known = [];
-	const rest = [];
+	const restPublic = [];
+	const restPrivate = [];
 	for (const key of Object.keys(obj)) if (KEY_INDEX.has(key)) known.push([key, obj[key]]);
-	else rest.push([key, obj[key]]);
+	else if (key.startsWith("_")) restPrivate.push([key, obj[key]]);
+	else restPublic.push([key, obj[key]]);
 	known.sort((a, b) => KEY_INDEX.get(a[0]) - KEY_INDEX.get(b[0]));
-	rest.sort((a, b) => byCodePoint(a[0], b[0]));
+	restPublic.sort((a, b) => byCodePoint(a[0], b[0]));
+	restPrivate.sort((a, b) => byCodePoint(a[0], b[0]));
 	const result = {};
-	for (const [key, value] of [...known, ...rest]) result[key] = DEPENDENCY_KEYS.has(key) && isPlainObject(value) ? sortDependencyMap(value) : value;
+	for (const [key, value] of [
+		...known,
+		...restPublic,
+		...restPrivate
+	]) result[key] = SORTED_MAP_KEYS.has(key) && isPlainObject(value) ? sortMapEntries(value) : value;
 	return result;
 };
-const DEPENDENCY_MAP_KEYS = [
+const STRIP_EMPTY_KEYS = [
 	"dependencies",
 	"devDependencies",
 	"peerDependencies",
-	"optionalDependencies"
+	"optionalDependencies",
+	"scripts"
 ];
-/** Remove dependency-map keys whose value is an empty object. */
+/** Remove map keys whose value is an empty object. */
 const stripEmptyDependencyMaps = (raw) => {
 	const result = { ...raw };
-	for (const key of DEPENDENCY_MAP_KEYS) {
+	for (const key of STRIP_EMPTY_KEYS) {
 		const value = result[key];
 		if (isPlainObject(value) && Object.keys(value).length === 0) delete result[key];
 	}
 	return result;
 };
+const DEFAULT_INDENT = 2;
+/**
+* Detect the indentation of a JSON source text from its first indented line:
+* `"\t"` for tab indentation, otherwise the leading run of spaces. Returns
+* `undefined` when no line is indented.
+*/
+const detectIndent = (source) => {
+	for (const line of source.split("\n")) {
+		const match = /^(\t+| +)\S/.exec(line);
+		if (match !== null) {
+			const indent = match[1];
+			return indent.startsWith("	") ? "	" : indent;
+		}
+	}
+};
+/**
+* Resolve a `PackageFormatOptions.indent` value to the `JSON.stringify` indent
+* argument: `"tab"` becomes a real tab, `"preserve"` reuses the indentation
+* detected from `sourceText` (falling back to the two-space default when no
+* source text or no indented line is available), and a number passes through.
+*/
+const resolveIndent = (indent, sourceText) => {
+	if (indent === "tab") return "	";
+	if (indent === "preserve") return sourceText === void 0 ? DEFAULT_INDENT : detectIndent(sourceText) ?? DEFAULT_INDENT;
+	return indent ?? DEFAULT_INDENT;
+};
 /**
 * Render an already-encoded package.json record to a JSON string, applying the
 * empty-map strip, canonical key ordering and a trailing newline unless the
@@ -103,4 +222,4 @@ const renderJson = (raw, options) => {
 };
 
 //#endregion
-export { renderJson, sortKeys, stripEmptyDependencyMaps };
+export { detectIndent, renderJson, resolveIndent, sortKeys, stripEmptyDependencyMaps };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/package-json",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"private": false,
 	"description": "package.json parsing, editing, validation and file IO as Effect schemas.",
 	"keywords": [
@@ -32,17 +32,18 @@
 	"exports": {
 		".": {
 			"types": "./index.d.ts",
-			"import": "./index.js"
+			"import": "./index.js",
+			"default": "./index.js"
 		},
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/npm": "0.2.0",
-		"@effected/semver": "0.1.0",
+		"@effected/npm": "0.2.1",
+		"@effected/semver": "0.1.1",
 		"spdx-expression-parse": "^4.0.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-beta.98"
+		"effect": "4.0.0-beta.99"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.9"
+      "packageVersion": "7.58.11"
     }
   ]
 }