@tertium/js

A reusable TypeScript library providing shared core utilities, entity models, and release automation scripts for JavaScript projects. Includes abstractions for APIs, authentication, filtering, logging, repositories, and domain entities (users, posts, comments).

Table of contents

• Installation
• Usage
  • Importing modules
  • Release scripts
  • Cleaning build folders
• Contributing

Installation

Install as a dependency or devDependency in your project:

npm install @tertium/js --save-dev

Usage

Importing modules

This package exposes subpath imports organized by domain. Import the specific modules you need rather than the package root.

Core utilities (./core/*)

Core modules provide foundational abstractions and utilities:

• API & HTTP: api, api-request, api-response — Types and utilities for API communication
• Authentication: auth — Auth helpers and utilities
• Data management: entity, entity-ref, repo — Base classes and types for entity management and repository patterns
• Filtering & forms: filter, form — Types for filtering and form handling
• Logging: log — Logging service and types
• Utilities: option, ref, time — General utility types for options, references, and time handling

Example:

import { Repo } from "@tertium/js/core/repo";
import type { ApiResponse } from "@tertium/js/core/api-response";
import { LogService } from "@tertium/js/core/log";

Entity models (./entities/*)

Domain entity classes and utilities for common models:

• User: User entity class and utilities
• Post: Post entity class and utilities
• Comment: Comment entity class and utilities

Example:

import { Post } from "@tertium/js/entities/post";
import { User } from "@tertium/js/entities/user";

Bitwarden CLI integration (./scripts/bw/*)

This package provides TypeScript utilities for integrating Bitwarden CLI into your project workflows. Use these to securely load environment variables from your Bitwarden vault.

Key modules:

• BitwaidenService — Service for vault access and secret management
• BwUtils — Utility functions for environment file handling
• run.ts — Wrapper script for executing commands with Bitwarden secrets

Quick start:

# Load env vars from vault and run a command
bun ./node_modules/@tertium/js/app/scripts/bw/run.ts {project} "your command"

# Example: build with secrets from vault
bun ./node_modules/@tertium/js/app/scripts/bw/run.ts weather-api "bun run build"

See app/scripts/bw/README.md for detailed documentation.

Deploy service (./scripts/deploy/*)

Centralized deployment service for managing application deployments to remote servers via SSH and PM2. Handles building, copying files, installing dependencies, and restarting processes.

Quick start:

Create a deploy.config.ts in your project:

import type { DeployConfig } from "@tertium/js/app/scripts/deploy";

export default {
  remoteHost: "tertium",
  deployPath: "/var/www/my-app",
  appName: "my-app",
  localDist: "./dist",
  tempPath: "/tmp/my-app-deploy"
} satisfies DeployConfig;

Add to package.json:

{
  "scripts": {
    "deploy": "bun ./node_modules/@tertium/js/app/scripts/deploy/run.ts ./deploy.config.ts",
    "deploy:skip-build": "bun ./node_modules/@tertium/js/app/scripts/deploy/run.ts ./deploy.config.ts --skip-build"
  }
}

Then deploy:

npm run deploy        # Build and deploy
npm run deploy:skip-build  # Skip build, deploy only

See app/scripts/deploy/README.md for detailed configuration options.

Release scripts

This package ships Node.js release helper scripts in scripts/. You can invoke them from your project's package.json by referencing the script file in node_modules:

{
  "scripts": {
    "release:patch": "node node_modules/@tertium/js/scripts/release.js patch",
    "release:minor": "node node_modules/@tertium/js/scripts/release.js minor",
    "release:major": "node node_modules/@tertium/js/scripts/release.js major"
  }
}

Briefly:

• Patch release: bump from main, rebase develop.
• Minor/Major releases: bump from develop, merge to main.

(See the script comments in scripts/release.js for full workflows.)

Cleaning build folders

This package provides a small cross-platform cleaner at scripts/clean.js that removes folders such as dist.

Notes:

• The script resolves paths from the current working directory and will skip targets that don't exist.
• It prefers fs.rmSync (Node 14.14+) and falls back to a small recursive remover for older Node versions.
• The script logs removed and skipped paths and sets a non-zero exit code on failure.

Using this script in your own repository

If you consume @tertium/js from another project, reference the script directly in your package.json scripts:

{
  "scripts": {
    "clean": "node node_modules/@tertium/js/scripts/clean.js",
    "clean:dist": "node node_modules/@tertium/js/scripts/clean.js dist"
  }
}

Then run from your project:

# Delete default (./dist)
npm run clean

# Pass multiple targets
npm run clean -- dist build .cache

# Run the dist shortcut
npm run clean:dist

Notes for consumers:

• Ensure @tertium/js is installed (as a dependency or devDependency) so the node_modules path exists.
• If you'd prefer a CLI-style experience (invokable via npx/pnpm dlx), we can add a bin entry to this package — tell me if you want that and I will add it and update README usage.

Contributing

Contributions, issues and pull requests are welcome. If you add features that change the exported types or scripts, please update the documentation here.