@job-search/tracker

A TypeScript library for tracking job applications • Get started

---

Features

⚡️ Database-agnostic

Built on Knex.js, the library works with PostgreSQL, MySQL, MariaDB, SQLite3, and MSSQL — swap backends with a single config change.

🗂️ Structured application tracking

Track job applications with a full status lifecycle, immutable activity ledger, linked contacts, per-company notes, and job source attribution — all as first-class entities.

🪪 vCard export

Export any contact as a standard vCard 3.0 file, ready to import into any address book.

🔑 Flexible ID strategies

Choose how primary keys are generated — delegate to the database engine, generate UUIDs, or use sequential integers — configured once in package.json.

📋 Immutable activity ledger

Every status change is automatically recorded as a system event. User-written notes can be appended at any time. The ledger is append-only.

🪵 Structured logging

Pino is used throughout. Bring your own logger instance or let the library create one. Log levels and transports are fully under your control.

Install

See the Getting Started guide for full setup instructions.

Prerequisites

• Node.js 18 or later
• A supported database driver installed alongside Knex (see Database Backends)

Quick install

npm install @job-search/tracker knex

Then add whichever database driver you need:

# SQLite (local / file-based)
npm install better-sqlite3

# PostgreSQL
npm install pg

# MySQL / MariaDB
npm install mysql2

Quick start

import { JobTracker } from "@job-search/tracker";

const tracker = new JobTracker({
  knex: {
    client: "better-sqlite3",
    connection: { filename: "./job-search.db" },
    useNullAsDefault: true,
  },
});

// Create tables (safe to call on every startup)
await tracker.initialize();

// Add a company and an application
const acme = await tracker.companies.create({
  name: "Acme Corp",
  website: "https://acme.com",
});

const app = await tracker.applications.create({
  title: "Senior TypeScript Engineer",
  company_id: acme.id,
  status: "applied",
});

// Status changes are automatically recorded in the activity ledger
await tracker.applications.updateStatus(app.application_id, "interview");

// Retrieve the full audit trail
const ledger = await tracker.applications.getActivity(app.application_id);

ID strategy

Set your preferred ID strategy once in package.json — no code changes needed:

{
  "job-tracker": {
    "idStrategy": "uuid"
  }
}

Value	Behaviour
db-native	Auto-increment integer managed by the database (default)
uuid	RFC 4122 v4 UUID generated in the application layer
sequential	Integer sequence managed by the application layer

See ID Strategies for a full comparison.

Example application

The app/ directory contains a complete example: an Express server with a REST API and a single-page web interface for managing your personal job search. It uses SQLite as its database so there is nothing to install or configure beyond npm install.

# Build the library
cd lib && npm install && npm run build

# Start the example app
cd ../app && npm install && npm run dev
# → http://localhost:3000

License

MIT