@bconnorwhite/package

A utility for reading package.json of the root project, and forming paths relative to it.

yarn add @bconnorwhite/package

API

package.json

Example usage:

import { pkg, PackageJSON } from "@bconnorwhite/package";

console.log(pkg.name); // "name" field from package.json
console.log(pkg.version); // "version" field from package.json
...

Structure

Package structure can be defined to make reading, writing, and finding files and directories easier. Definitions will be added on top of the default structure, which tracks package.json and the file marked by main in packge.json.

Example usage:

import { define, defineFrom, Directory, File } from "@bconnorwhite/package";

const structure = define({
  source: {
    name: "src",
    files: {
      index: {
        name: "index.ts"
      }
    }
  },
  build: {
    files: {}
  },
  gitignore: {
    name: ".gitignore"
  }
});

export function getSourceDir() {
  return structure.files().source as Directory;
}

export function getBuildDir() {
  return structure.files().build as Directory;
}

export function getGitIgnore() {
  return structure.files().gitignore as File<string>;
}

Types

type File<T> = {
  name: string;
  path: string;
  relative: string;
  exists: () => Promise<boolean | undefined>;
  read: () => Promise<T | undefined>;
  readSync: () => T | undefined;
  write: (content?: T) => Promise<void>;
  writeSync: (content?: T) => void;
};

type JSONFile<T extends JSONObject> = File<T> & {
  merge: (content: T = {}) => Promise<void>;
  mergeSync: (content: T = {}) => void;
};

type Directory = {
  name: string;
  path: string;
  relative: string;
  files: ((...args: any) => Paths);
  exists: () => Promise<boolean | undefined>;
  read: () => Promise<string[]>;
  write: () => Promise<boolean>;
  writeSync: () => boolean;
};

Default Structure Functions

Types:

import {
  getRootDir,
  getMain,
  getPackageJSON
} from "@bconnorwhite/package";

getRootDir() => Directory;
// project root directory

getPackageJSON() => File<PackageJSON>;
// package.json file

getMain() => File<string>;
// file for "main" in package.json

Package Functions

import {
  getBase,
  getPath,
  getRelative,
  exists,
  WorkspacePackage
}

getBase() => string;// process.env.PWD
// working directory process was started from

getPath(parent: string, name: string) => string;
// absolute path

getRelative(path: string) => string;
// path relative to getBase()

exists(relative: string) => Promise<boolean>;
// check if path exists relative to root of the package

Yarn Workspaces

Types:

import {
  isWorkspace,
  isWorkspaceRoot,
  getWorkspacePackages,
  existsWorkspace,
  WorkspacePackages,
  WorkspacePackage
}

isWorkspace() => Promise<string | undefined>;
// will return true for any package in a yarn workspace

getWorkspacePath(name: string) => Promise<string | undefined>;
// absolute workspace path

getWorkspaceRelative(relative: string) => Promise<string | undefined>;
// path relative to workspace root

existsWorkspace(relative: string) => Promise<boolean | undefined>;
// check if path exists relative to workspace root

isWorkspaceRoot() => Promise<boolean>;
// will return true if run from the root of a yarn workspace

getWorkspacePackages() => Promise<WorkspacePackages | undefined>;
// list all packages in a workspace

type WorkspacePackages = {
  [name: string]: WorkspacePackage;
}

type WorkspacePackage = {
  location: string;
  workspaceDependencies: string[];
  mismatchedWorkspaceDependencies: string[];
}