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/core

v0.5.0

Published

Double-entry ledger domain primitives and application contracts for LuxLedger.

Readme

@luxledger/core

Domain-first ledger library for LuxLedger.

Design goals

  • Explicit invariants in domain classes/use-cases.
  • Zero framework/runtime dependencies in core domain model.
  • Stable contracts (input.interface.ts / repository.interface.ts / use-case result contracts).
  • Deterministic behavior: same input -> same domain decision.

Package structure

  • src/base
    • Shared primitives and abstractions: DomainError, Result, UnitOfWork, Clock, Id, Money.
  • src/application
    • App-facing contracts and error types for service/repository boundaries.
  • src/utils
    • Shared helper utilities such as assertNonEmpty.
  • src/tenant
    • Tenant model contracts.
  • src/ledger
    • Ledger model contracts.
  • src/account
    • Account model contracts.
  • src/transaction
    • Transaction invariants, JSON metadata contracts, and create transaction use-case.
  • src/credit-grant
    • Grant issuance plus immutable consumption/compensation lineage and derived capacity invariants.
  • src/entry
    • Entry contracts.
  • src/api-key
    • API key contracts.

Conventions

Each domain module follows this layout:

  • entity.ts - domain entity/value object.
  • input.interface.ts - use-case input contracts.
  • repository.interface.ts - persistence port contract.
  • index.ts - module exports.

Executable domain and application behavior

Core contains executable transaction/account invariants and application services for the supported ledger surface, including:

  • EntryEntity
  • TransactionEntity
  • CreateTransactionUseCase
  • ledger and account validation
  • transaction, balance, bounded statement, hold, API-key, and reconciliation services
  • deterministic reconciliation matching
  • credit grant amount, consumption/compensation consistency, and nonnegative capacity validation

Persistence-dependent atomicity and idempotency are implemented by adapters against these contracts. See the repository invariants guide for the guarantees exposed to integrators. Credit grant posting and lot reconciliation are documented in the credit grants guide.

Transaction metadata

CreateTransactionInput accepts optional metadata, a typed JSON object for host identifiers and other transaction context. Core passes metadata through without cloning, freezing, or runtime normalization. Persistence, serialization, idempotency comparison, and HTTP exposure are adapter concerns. Omitted metadata remains distinct from an empty object.

Example

import { CreateTransactionUseCase } from '@luxledger/core';
import { assertNonEmpty } from '@luxledger/core/utils';

const useCase = new CreateTransactionUseCase(repository);
assertNonEmpty(input.tenantId, 'tenantId is required');
const result = await useCase.execute(command);

Migration strategy

  1. Keep API/DB adapters in the host app.
  2. Move invariant checks into module use-cases.
  3. Keep repository interfaces in @luxledger/core, implementations outside.

Integration

Application hosts should normally compose this package through a route adapter and @luxledger/postgres-adapter. See the repository integration guide and architecture overview.

Before production use, pin compatible LuxLedger package versions and cross-check behavior against the released OpenAPI shipped with that version; see versioning and publication.

List filters

Every list/list* service read accepts an optional persistence-neutral where. All list methods accept it inside an explicit pagination query with limit (1–200) and optional cursor, returning { data, nextCursor }. API-key lists receive the authenticated actor separately; their query cannot select a tenant.

import { accountListFilter, type WhereFor } from '@luxledger/core/application';

const where: WhereFor<typeof accountListFilter> = {
  name: { eq: 'Wallet' },
  currency: { in: ['USD', 'EUR'] },
  balanceMinor: { gte: 0n },
  code: { ne: null },
};
const page = await services.accounts.list({ tenantId, ledgerId, limit: 25, where });
const ledgers = await services.ledgers.list({ tenantId, limit: 25, where: { name: { eq: 'Main' } } });
const keys = await services.apiKeys.listApiKeys(adminActor, { limit: 25, where: { revokedAt: { eq: null } } });
const results = await services.reconciliation.listResults({
  tenantId, runId, limit: 25, where: { status: { eq: 'conflict' } },
});

All fields and operators are combined with AND. Supported operators are eq, ne, in (1–100 non-null values), plus gt, gte, lt, lte for dates and numbers (including bigint amounts). Use Date objects and bigint values, not JSON strings. Use eq: null and ne: null for nullable fields. Other comparisons follow SQL null semantics, so ne: 'value' does not match null rows. Empty where means no additional restriction; empty field filters, excluded fields, unknown operators, non-scalar values, invalid dates, and non-finite numbers throw InvariantViolationError. Field-specific types, enum values, and nullability are checked by TypeScript using the existing core entities/read models; they are not revalidated against a separate runtime schema. Hosts accepting untyped input must validate it before invoking these services.

Each operation uses a named filter policy beside its entity or read model. Policies are readonly exclusion arrays, created with defineListFilter<Model>()(['field']), not a duplicate list of model fields. The two calls let TypeScript accept the explicit model type while inferring the exact excluded keys. WhereFor<typeof policy> derives scalar field types from the model. Consumers use PaginationQuery<typeof policy> directly; a named query type is needed only when it adds operation-specific fields:

import {
  type PaginationQuery,
  transactionListFilter,
} from '@luxledger/core/application';

export interface TransactionPaginationQuery
  extends PaginationQuery<typeof transactionListFilter> {
  ledgerId?: string;
}

PaginationQuery takes the filter policy itself and derives where through WhereFor. It defaults to no filters (never). Shared pagination helpers accept BasePaginationQuery to inspect tenant, limit and cursor independently of the operation filter policy. Cursors are bound to the tenant, resource, fixed scope and where. Reuse the same filter when following nextCursor; consume every page instead of assuming the first page is complete.

| Service method | Filter policy | | --- | --- | | accounts.list | accountListFilter | | transactions.list | transactionListFilter | | transactions.listEntries | entryListFilter | | assets.list | assetListFilter | | ledgers.list | ledgerListFilter | | apiKeys.listApiKeys | apiKeyListFilter | | reconciliation.listRules | reconRuleListFilter | | reconciliation.listResults | reconResultListFilter | | creditGrants.list, creditGrants.listLots | creditGrantListFilter | | creditGrants.listLineageByGrant, creditGrants.listLineageByTransaction | creditLineageListFilter | | balances.listHistory | balanceHistoryListFilter |

Policies and WhereFor are exported from @luxledger/core/application. Entity policies are also exported from their domain entry points, such as @luxledger/core/transaction. ID value objects use string filter values. Persisted entry IDs and entry/transaction timestamps are non-nullable in filters.

Core validates policy exclusions, query structure and scalar values. The persistence adapter checks field existence against its existing runtime schema and omits columns that are absent from the domain read model (for example, transaction hold linkage). An alternative adapter must perform the same field-existence check before applying filters. New scalar model fields are eligible unless excluded by the operation policy; review exclusions when adding private fields. No separate resource-name registry exists.

Lot filters target persisted grant fields such as reference and expiration, not derived remaining/consumed capacity. Entry amounts use signedAmountMinor; lineage amounts use amountMinor. Metadata/JSON paths and API key hashes are not filterable.

PostgreSQL applies these predicates before pagination, alongside mandatory tenant, ledger/account, time range, fixed filters, and cursor conditions. Filters cannot override these scopes. Keep the same where when following a cursor: changing or removing it is rejected. Field/operator key order does not matter; in value order must remain the same. Existing unfiltered cursor formats remain compatible (including the legacy history codec). HTTP adapters expose pagination as limit/cursor and serialize typed filters through where.

Reconciliation result pages use reconResultListFilter; candidate ID arrays are excluded from filtering. Existing reconciliation run responses and reports are unchanged.