IF Commons GitHub

pack-library

The package of a library of commons (commons 0032-libraries-by-concern FR-005, FR-013): the library's sources compiled by the TypeScript 7 compiler into ECMAScript modules and their declarations, the package.json that is published (each exports entry naming its types, the source for Bun and the compiled file for everything else), and the tarball. The same inspection that the packer makes before it packs is inspectPackage, which a test runs again on the tarball it unpacks.

bun tools/pack.ts of a library: pack dist/<scope>-<name>-<version>.tgz bun tools/pack.ts --check the same, and print what was found; exit 1 where anything was

A library's own package.json stays private and names its entries by their sources ("./src/mod.ts"); nothing is published from it by hand. A library that depends on another library of commons imports it by package name, and the published package depends on it at the version that library has in this repository. The declarations are written with .js specifiers (the compiler leaves .ts in a .d.ts, which a consumer's compiler cannot read), and only the declarations that the entries reach are published in a bundle. A package is refused where an entry has no declaration, where a declaration reached imports a file that is not in the package or a package that is not a dependency, or where the code imports a package that is not on npm.

A package that is also a command, or whose code imports what is not yet on npm, is packed with bundle: each entry's code and the command's are one bundle (bun build), the declarations are emitted from the sources and only those the entries reach are published, and whatever they import must be a package of npm that the package depends on.

Source: commons/libraries/src/pack-library.ts

1 of 17 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

SCOPEconstno test imports it
const SCOPE: "@intellectual-frontiers"

The scope of the packages of commons.

Findingstypeno test imports it
type Findings = readonly string[];

What is wrong with a package, one sentence each.

isObjectconstno test imports it
const isObject: (v: unknown) => v is Readonly<Record<string, unknown>>

Whether a value is a plain object (not an array, not null).

noDotconstno test imports it
const noDot: (p: string) => string

A path of a manifest without its leading ./, with / separators.

filesUnderfunction
function filesUnder(root: string, dir?: string): readonly string[]

The files under a folder, from the folder, in order (node_modules is not looked into).

Imported by 15 tests of the run (15 passed, 0 failed): the library's results

DOC_BLOCKconstno test imports it
const DOC_BLOCK: RegExp

The documentation blocks of a source (a block comment that begins a line): an example in one names what a reader may write, not what the module imports.

specifiersOfconstno test imports it
const specifiersOf: (source: string) => readonly string[]

The specifiers a source imports: not those of a comment, and not the text of a string that only looks like an import.

packageOffunctionno test imports it
function packageOf(specifier: string): string | undefined

The package a bare specifier names (@scope/name/sub is @scope/name), or undefined for a relative path, a node: builtin or a data: URL.

targetsOffunctionno test imports it
function targetsOf(entry: unknown): Readonly<Record<string, string>>

The target of an export entry for each condition: the string, or the types, bun or default of an object.

reachableDeclarationsfunctionno test imports it
function reachableDeclarations(stage: string, manifest: Readonly<Record<string, unknown>>): { readonly reached: ReadonlySet<string>; readonly findings: Findings; }

The declarations that the entries of a package reach, by relative imports from the types of each entry, and what is wrong on the way (a declaration that is not there).

inspectPackagefunctionno test imports it
function inspectPackage(stage: string): Findings

What is wrong with the package staged in a folder (the files of the tarball, package/ unpacked): see the remarks of this module.

rewriteDeclarationSpecifiersfunctionno test imports it
function rewriteDeclarationSpecifiers(source: string): string

Writes the declarations with .js in the place of .ts in their relative specifiers.

tarballNameconstno test imports it
const tarballName: (name: string, version: string) => string

The tarball's name for a package: @scope/name at a version is scope-name-version.tgz.

Packedtypeno test imports it
type Packed = { readonly stage: string; readonly tarball: string | undefined; readonly findings: Findings; readonly manifest: Json };

What packing a library made: the staging folder, the tarball, the findings and the manifest.

namesNodeTypesfunctionno test imports it
function namesNodeTypes(folder: string): boolean

Whether a declaration of the package names a node: module: a package whose types name Node's needs @types/node where it is type-checked (a peer dependency, FR-013 of 0032-libraries-by-concern).

PackOptionstypeno test imports it
type PackOptions = { /** Types the compiler is given (`["node"]` for a library that names Node's). */ readonly types… (1515 characters)
type PackOptions = {
  /** Types the compiler is given (`["node"]` for a library that names Node's). */
  readonly types?: readonly string[];
  /**
   * Commands of a package that is not a bundle: each command's name and the module, in `src/`, whose `main(argv)` gives the exit status; the package gets a one-line launcher for each (`<command>.mjs`, which Node and Bun run), made
   * from the compiled module. The files under `src/` that are not TypeScript (a stylesheet a module reads beside itself) are published beside the sources and beside the compiled modules.
   */
  readonly launchers?: Readonly<Record<string, string>>;
  /** Packages the published package may use where they are installed beside it and does not need (loaded by name at run time): written as optional peer dependencies, name and range. */
  readonly optionalPeers?: Readonly<Record<string, string>>;
  /** A bundled package: the code of each entry and of each command is one file (`bun build`), and only the declarations the entries reach are published. */
  readonly bundle?: {
    /** The commands: their name, and the source that is the command's entry from the library's folder. */
    readonly bin?: Readonly<Record<string, string>>;
    /** The README that is published, where it is more than the common one. */
    readonly readme?: string;
    readonly keywords?: readonly string[];
    /** Files of the library's folder that are published beside the others (`CREDITS.md`). */
    readonly extraFiles?: readonly string[];
  };
};

What packing a library is told: its folder, where to stage it and whether to make the tarball.

packLibraryfunctionno test imports it
function packLibrary(root: string, options?: PackOptions): Promise<Packed>

Builds and stages the package of the library at root (a folder commons/<name>/ with a package.json and sources in src/), inspects it and, where nothing is wrong, packs it.

Titles, headings, exports, tables, columns and requirements. Esc closes.