Reads a package file and passes a proxied PackageJson to a callback (the callback may mutate it in-place or return a new object). The updated package is then written back using the same file format (.json/.json5/.yaml). The proxy auto-creates common map fields (e.g. scripts, dependencies) when accessed.
Returns a new PackageJson that reorders known top-level fields according to the convention and alphabetically sorts certain nested maps (like dependencies, devDependencies, optionalDependencies, peerDependencies and scripts). Unknown top-level keys retain their original relative order. The input object is not mutated.
import { sortPackage } from "pkg-types";const sorted = sortPackage(pkg);
normalizePackage
Normalizes a PackageJson for stable output: sorts top-level fields and dependency maps, and removes dependency fields (dependencies, devDependencies, optionalDependencies, peerDependencies) if they are not plain objects. Returns a new normalized object.
import { normalizePackage } from "pkg-types";const normalized = normalizePackage(pkg);
import { findNearestFile } from "pkg-types";const filename = await findNearestFile("package.json");
findFarthestFile
import { findFarthestFile } from "pkg-types";const filename = await findFarthestFile("package.json");
resolveLockfile
Find path to the lock file (yarn.lock, package-lock.json, pnpm-lock.yaml, npm-shrinkwrap.json, bun.lockb, bun.lock, deno.lock, upm.lock) or throws an error.
import { resolveLockfile } from "pkg-types";const lockfile = await resolveLockfile(".");
import { findWorkspaceDir } from "pkg-types";const workspaceDir = await findWorkspaceDir(".");
Git Configuration
resolveGitConfig
Finds closest .git/config file.
import { resolveGitConfig } from "pkg-types";const gitConfig = await resolveGitConfig(".");
readGitConfig
Finds and reads closest .git/config file into a JS object.
import { readGitConfig } from "pkg-types";const gitConfigObj = await readGitConfig(".");
writeGitConfig
Stringifies git config object into INI text format and writes it to a file.
import { writeGitConfig } from "pkg-types";await writeGitConfig(".git/config", gitConfigObj);
parseGitConfig
Parses a git config file in INI text format into a JavaScript object.
import { parseGitConfig } from "pkg-types";const gitConfigObj = parseGitConfig(gitConfigINI);
stringifyGitConfig
Stringifies a git config object into a git config file INI text format.
import { stringifyGitConfig } from "pkg-types";const gitConfigINI = stringifyGitConfig(gitConfigObj);
Types
Note: In order to make types work, you need to install typescript as a devDependency.
You can directly use typed interfaces:
import type { TSConfig, PackageJson, GitConfig } from "pkg-types";
Define Utilities
You can use define utilities for type support and auto-completion when working in plain .js files. These functions simply return the input object but provide TypeScript type hints.
definePackageJSON
Provides type safety and auto-completion for package.json objects.
import { definePackageJSON } from "pkg-types";const pkg = definePackageJSON({ name: "my-package", version: "1.0.0", // TypeScript will provide auto-completion here});
defineTSConfig
Provides type safety and auto-completion for tsconfig.json objects.
import { defineTSConfig } from "pkg-types";const tsconfig = defineTSConfig({ compilerOptions: { target: "ES2020", // TypeScript will provide auto-completion here },});
defineGitConfig
Provides type safety and auto-completion for git config objects.
import { defineGitConfig } from "pkg-types";const gitConfig = defineGitConfig({ user: { name: "John Doe", email: "john@example.com", }, // TypeScript will provide auto-completion here});