@epubknowledge/common

Shared runtime helpers for the Epub Knowledge package ecosystem.

Install

This package is intended to be published to the public npm registry, so consuming repos can install it with no extra registry configuration or GitHub token:

pnpm:

pnpm add @epubknowledge/common

yarn:

yarn add @epubknowledge/common

npm:

npm install @epubknowledge/common

Requires Node.js >= 22.0.0.

Publishing

Maintainers publish this package to npm as the primary install target, and the release workflow mirrors the same version to GitHub Packages for authenticated consumers that still want it there.

Publish prerequisites

• The @epubknowledge scope must exist on npm and the publisher must have permission to publish under it.
• npm trusted publishing must be configured for the release-package.yml workflow on npmjs.com before CI publish will succeed.
• Local publishing uses npm login.
• GitHub Actions publishing uses GitHub OIDC trusted publishing for npm and the built-in GITHUB_TOKEN for the GitHub Packages mirror.

Publish from CI

The release workflow runs when a GitHub release is published or when it is started manually. Before any publish step, it runs tests, builds the package, verifies the tarball contains compiled dist/*.js and dist/*.d.ts assets, and smoke-tests a temporary consumer install for both runtime and type-only imports. It then publishes that tarball to https://registry.npmjs.org with provenance and mirrors the same tarball to https://npm.pkg.github.com.

on:
  release:
    types: [published]
  workflow_dispatch:

Publish locally

npm publish --access public

Optional GitHub Packages mirror install

Most consumers should use the public npm install shown above. If a repo intentionally wants the GitHub Packages mirror instead, configure that consuming repo with:

@epubknowledge:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Importing

Import from the documented subpath exports only. There is currently no root barrel export, so prefer paths like @epubknowledge/common/dir.

Public subpath exports

• @epubknowledge/common/constants (internal) — exported for use by other @epubknowledge packages only; may change without notice between minor versions; external consumers should not depend on it
• @epubknowledge/common/dir
• @epubknowledge/common/epub
• @epubknowledge/common/file
• @epubknowledge/common/misc
• @epubknowledge/common/objectSetup
• @epubknowledge/common/paths
• @epubknowledge/common/resetMemory
• @epubknowledge/common/tmp
• @epubknowledge/common/types
• @epubknowledge/common/zip

JavaScript example

import { isDir, verifyBookDir } from '@epubknowledge/common/dir'
import { fileExists } from '@epubknowledge/common/file'

if (isDir('./book') && fileExists('./book/chapter.xhtml')) {
  console.log(verifyBookDir('./book'))
}

TypeScript example

No separate @types package is needed. This package ships its own declaration files, so TypeScript consumers can use the same import paths as JavaScript consumers and import type for type-only imports.

import { epubMove } from '@epubknowledge/common/epub'
import type { EpubObj, EpubMoveResult } from '@epubknowledge/common/types'

export async function moveBook(book: EpubObj): Promise<EpubMoveResult> {
  return epubMove(book)
}

TypeScript consumers should use modern package resolution (moduleResolution: 'bundler', 'node16', or 'nodenext') so package subpath exports resolve cleanly.

Import Readiness Plan

The repo plan for publishing and verifying consumer installs lives in docs/importing.md.

Development

npm test
npm run test:coverage
npm run build

Environment

Create a .env file in the project root to configure the tmp directory:

TMP_DIR=/path/to/your/tmp

If TMP_DIR is missing, the tmp module creates a system tmp directory for the current run. It only writes that path back to .env when create(..., true) is used and the .env file already exists.