npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@luxledger/postgres-adapter

v0.5.0

Published

PostgreSQL persistence adapter for LuxLedger using Drizzle ORM.

Readme

@luxledger/postgres-adapter

Drizzle/PostgreSQL adapter for @luxledger/core.

This package contains infrastructure implementations:

  • DrizzleLedgerRepository
  • Drizzle schema and row mappers
  • PostgreSQL client factory
  • luxLedgerDrizzleSchemaPath for consumer drizzle.config.ts files

It is intentionally tied to Drizzle and Postgres.

PostgreSQL 16 is the supported persistence model.

State-changing repository operations use explicit PostgreSQL transactions. The adapter enforces persistence-level tenant scoping, atomicity, and transaction-reference idempotency required by the repository invariants guide.

Transaction metadata is stored as nullable PostgreSQL jsonb on the immutable transaction header. Omitted metadata is SQL NULL, which remains distinct from an empty object. Metadata must be a JSON object no larger than 16 KiB in PostgreSQL's canonical JSON text representation and cannot be updated after insertion. The limit keeps idempotency comparisons and transaction reads bounded while leaving room for compact integration context. Idempotent retries use PostgreSQL jsonb equality: object key order is ignored, array order is significant, and any semantic metadata difference is a payload conflict.

Use metadata for stable external IDs, provider references, flags, and other compact context needed to interpret a transaction. Do not embed full provider payloads, audit histories, documents, binary data, or mutable records. Store large data in the owning system and keep only its stable reference in transaction metadata.

Host-composable unit of work

Use createUnitOfWork when a host row or outbox record must commit atomically with LuxLedger operations:

import { TenantId } from '@luxledger/core';
import { createDbClient, createUnitOfWork } from '@luxledger/postgres-adapter';
import { purchaseOutbox } from './db/schema';

const client = createDbClient({ hostSchema: { purchaseOutbox } });
const unitOfWork = createUnitOfWork(client);

await unitOfWork.run(new TenantId(tenantId), async ({ tx, services }) => {
  await tx.insert(purchaseOutbox).values({
    tenantId,
    purchaseId,
    eventType: 'purchase.created',
  });
  await services.transactions.create(posting);
});

The callback's Drizzle tx and tenant-scoped services share one transaction and RLS context. Register host tables through hostSchema to use the typed relational API such as tx.query.purchaseOutbox; use tx.execute(sql\...`)for raw parameterized SQL. A callback failure rolls back every write. Do not retaintx` after the callback completes. Nested unit-of-work calls, cross-tenant service inputs, and unscoped service operations are rejected. Existing repository/service calls outside this API keep their current transaction behavior.

Hosts must preserve the documented account/grant lock order when doing their own locking before ledger calls. The unit of work does not retry transactions or provide distributed transaction/outbox delivery.

Credit-grant allocation locking

Mutations that touch grant-enabled accounts lock those account rows in account-ID order before locking grants or writing ledger history. Ordinary accounts are not pre-locked; their balance projection is updated atomically in account-ID order, and PostgreSQL takes the row lock for the duration of that update and transaction. Holds read the immutable grant capability without a row lock and reject grant-enabled accounts. Grant issuance never converts an existing account or scans its history. Transaction posting groups inserted entries by account and processes accounts in account-ID order. For each grant-enabled account it performs one SELECT ... FOR UPDATE of the account's grants, ordered by expires_at ASC NULLS LAST, created_at ASC, id ASC. A grant-enabled account with debit entries loads one latest immutable capacity version per grant and updates that in-memory projection after every allocation so later entries in the same transaction observe earlier allocations. Each new lineage row appends its next cumulative version in the same transaction; versions are rebuildable from authoritative ledger entries and lineage and cannot be updated or deleted. Reversals load the original transaction lineage once per grant-enabled account and copy each original entry's exact grant split.

Grant locks remain held until the posting transaction commits or rolls back. Lineage rows, ledger entries, balance updates, and snapshots are written in that same transaction. The database constraints, row-level tenant policy, and deferred attribution and exact-compensation triggers remain the final boundary checks; there is no mutable authoritative grant-balance column.

Configuration

The client reads these package-owned variables when equivalent constructor options are not passed:

  • DATABASE_URL (required)
  • DB_POOL_MAX (default 10)
  • DB_IDLE_TIMEOUT in seconds (default 20)
  • DB_CONNECT_TIMEOUT in seconds (default 10)

JWT, rate-limit, bootstrap, port, and shutdown configuration belongs to the host application, not this package. Environment files must be loaded by the host/runtime before createDbClient is called; Node.js does not load .env automatically.

Drizzle config

import { luxLedgerDrizzleSchemaPath } from '@luxledger/postgres-adapter/drizzle-config';
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: ['./src/db/schema.ts', luxLedgerDrizzleSchemaPath],
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Apply migrations before starting application code that depends on a newer adapter schema. Numbered migrations upgrade the consolidated 0000 baseline in place; reset databases created by the retired history that predates that baseline. Package downgrade does not roll back a database; follow the repository upgrade procedure.

Before production use, pin compatible LuxLedger package versions and review the documentation publication checklist.