@effected/package-json 0.1.0 → 0.3.0

package/Package.js

@@ -1,11 +1,11 @@
 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";
-import { CatalogResolver, WorkspaceResolver } from "@effected/npm";
+import { CatalogResolver, DependencySpecifier, WorkspaceResolver } from "@effected/npm";
 import { Effect, Function, HashMap, Option, Pipeable, Schema, SchemaTransformation } from "effect";
 import { SemVer } from "@effected/semver";
 
@@ -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
@@ -106,23 +106,12 @@ const makeWire = (Class) => {
 		encode: (encoded) => {
 			const { rest, ...known } = encoded;
 			return {
-				...known,
-				...rest ?? {}
+				...rest ?? {},
+				...known
 			};
 		}
 	})));
 };
-const applyWorkspaceModifier = (specifier, version) => {
-	const modifier = specifier.slice(10);
-	if (modifier === "*" || modifier === "") return version;
-	if (modifier === "^") return `^${version}`;
-	if (modifier === "~") return `~${version}`;
-	return modifier;
-};
-const catalogName = (specifier) => {
-	const name = specifier.slice(8);
-	return name.length === 0 ? Option.none() : Option.some(name);
-};
 /**
 * A package.json document as a rich `Schema.Class`: typed known fields, a
 * `rest` catch-all preserving unknown top-level fields across a read/edit/write
@@ -290,20 +279,33 @@ var Package = class Package extends Schema.Class("Package")({
 	static removeScript = Function.dual(2, (pkg, name) => pkg.copyWith({ scripts: HashMap.remove(pkg.scripts, name) }));
 	/**
 	* Resolve `catalog:` and `workspace:` specifiers across all four dependency
-	* maps using the `CatalogResolver` and `WorkspaceResolver` from context.
-	* Specifiers the resolvers return `None` for are left unchanged. This is the
-	* explicit resolution step — `PackageJsonFile.write` never resolves.
+	* maps using the `CatalogResolver` and `WorkspaceResolver` from context,
+	* classifying and projecting through `@effected/npm`'s `DependencySpecifier`
+	* statics (`workspace:` uses the pnpm publish-time projection; the alias
+	* form `workspace:<name>@<range>` resolves the TARGET package's version and
+	* becomes the published `npm:<name>@<range>` alias). Specifiers the
+	* resolvers return `None` for are left unchanged — resolution still
+	* succeeds. A `CatalogResolver` whose catalog assembly failed surfaces
+	* typed as `@effected/npm`'s `CatalogAssemblyError`, alongside the
+	* contracts' `DependencyResolutionError`. This is the explicit resolution
+	* step — `PackageJsonFile.write` never resolves.
+	*
+	* @remarks
+	* Leaves unresolvable specifiers unchanged. For fail-typed manifest
+	* resolution over the tolerant model, see `@effected/npm`'s
+	* `Manifest#resolve`.
 	*/
 	static resolve = Effect.fn("Package.resolve")(function* (pkg) {
 		const workspace = yield* WorkspaceResolver;
 		const catalog = yield* CatalogResolver;
 		const resolveMap = Effect.fn("Package.resolve.map")(function* (map) {
 			let next = map;
-			for (const [name, specifier] of HashMap.entries(map)) if (specifier.startsWith("workspace:")) {
-				const version = yield* workspace.versionOf(name);
-				if (Option.isSome(version)) next = HashMap.set(next, name, applyWorkspaceModifier(specifier, version.value));
-			} else if (specifier.startsWith("catalog:")) {
-				const range = yield* catalog.rangeOf(name, catalogName(specifier));
+			for (const [name, specifier] of HashMap.entries(map)) if (DependencySpecifier.isWorkspace(specifier)) {
+				const target = Option.getOrElse(DependencySpecifier.workspaceTargetOf(specifier), () => name);
+				const version = yield* workspace.versionOf(target);
+				if (Option.isSome(version)) next = HashMap.set(next, name, DependencySpecifier.resolveWorkspace(specifier, version.value));
+			} else if (DependencySpecifier.isCatalog(specifier)) {
+				const range = yield* catalog.rangeOf(name, DependencySpecifier.catalogNameOf(specifier));
 				if (Option.isSome(range)) next = HashMap.set(next, name, range.value);
 			}
 			return next;

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

@@ -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.
@@ -180,7 +182,7 @@ console.log(Effect.runSync(program));
 // => ["^4.0.0", "^1.4.0"]
 ```
 
-The `workspace:` range modifier is honored: `workspace:*` takes the bare version, `workspace:^` and `workspace:~` prefix it, and an explicit modifier is used as-is.
+The `workspace:` range modifier is honored: `workspace:*` takes the bare version, `workspace:^` and `workspace:~` prefix it, and an explicit modifier is used as-is. The projection is `@effected/npm`'s `DependencySpecifier` statics with full pnpm publish semantics: the alias form `workspace:<name>@<range>` resolves the *target* package's version and becomes the `npm:<name>@<range>` alias pnpm publishes, and a blank catalog name selects the default catalog. A failed catalog assembly surfaces typed as `@effected/npm`'s `CatalogAssemblyError`, alongside the contracts' `DependencyResolutionError`.
 
 ## Errors
 
@@ -206,7 +208,7 @@ Every failure is a `Schema.TaggedErrorClass` routed with `Effect.catchTag`. Caus
 - `Package.schema` / `Package.wireFor` — the open-JSON ↔ class wire codec, and the factory that builds one for a `.extend()`ed subclass so its custom fields decode as typed members instead of falling into `rest`.
 - `PackageJsonFile` — the IO surface: `read` and `write` over core `FileSystem` / `Path`, with the platform implementation supplied at the edge.
 - `PackageValidator` — rule-based validation aggregating every failure, with the default rule set, a parameterized `layerRules` factory, and the publish-gate rules `noUnresolvedDepsRule` and `noLocalDepsRule`.
-- `Package.resolve` — `catalog:` and `workspace:` expansion over the `@effected/npm` contracts, as an explicit step that `write` never performs for you.
+- `Package.resolve` — `catalog:` and `workspace:` expansion over the `@effected/npm` contracts with pnpm's publish-time projection (alias form included), as an explicit step that `write` never performs for you.
 - `PackageName`, `DependencySpecifier`, `Dependency`, `SpdxLicense`, `PackageManager`, `Person`, `DevEngine` — the leaf concepts, each owning its own statics, brand and error, usable independently of `Package`.
 - Field schemas (`DependencyMapField`, `BinField`, `ExportsField`, `RepositoryField`, `PublishConfigField`, `PeerDependenciesMetaField`, `StringMapField`) exported for subclasses that extend the model.
 

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`). */
@@ -525,11 +542,23 @@ declare class Package extends Package_base {
   };
   /**
    * Resolve `catalog:` and `workspace:` specifiers across all four dependency
-   * maps using the `CatalogResolver` and `WorkspaceResolver` from context.
-   * Specifiers the resolvers return `None` for are left unchanged. This is the
-   * explicit resolution step — `PackageJsonFile.write` never resolves.
+   * maps using the `CatalogResolver` and `WorkspaceResolver` from context,
+   * classifying and projecting through `@effected/npm`'s `DependencySpecifier`
+   * statics (`workspace:` uses the pnpm publish-time projection; the alias
+   * form `workspace:<name>@<range>` resolves the TARGET package's version and
+   * becomes the published `npm:<name>@<range>` alias). Specifiers the
+   * resolvers return `None` for are left unchanged — resolution still
+   * succeeds. A `CatalogResolver` whose catalog assembly failed surfaces
+   * typed as `@effected/npm`'s `CatalogAssemblyError`, alongside the
+   * contracts' `DependencyResolutionError`. This is the explicit resolution
+   * step — `PackageJsonFile.write` never resolves.
+   *
+   * @remarks
+   * Leaves unresolvable specifiers unchanged. For fail-typed manifest
+   * resolution over the tolerant model, see `@effected/npm`'s
+   * `Manifest#resolve`.
    */
-  static readonly resolve: (pkg: Package) => Effect.Effect<Package, import("@effected/npm").DependencyResolutionError, CatalogResolver | WorkspaceResolver>;
+  static readonly resolve: (pkg: Package) => Effect.Effect<Package, import("@effected/npm").CatalogAssemblyError | import("@effected/npm").DependencyResolutionError, CatalogResolver | WorkspaceResolver>;
   /**
    * Serialize to a formatted package.json string: encode through the wire
    * codec (flattening `rest`), then apply the canonical key order, dependency
@@ -610,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>;
@@ -743,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.1.0",
+	"version": "0.3.0",
 	"private": false,
 	"description": "package.json parsing, editing, validation and file IO as Effect schemas.",
 	"keywords": [
@@ -37,7 +37,7 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/npm": "0.1.0",
+		"@effected/npm": "0.2.0",
 		"@effected/semver": "0.1.0",
 		"spdx-expression-parse": "^4.0.0"
 	},

package/tsdoc-metadata.json

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