typescript

A few TypeScript libraries I wrote and use often

@pband/global (1.0.1-rc.4)

Published 2026-11-09 11:11:14 +01:00 by pascal

Installation

@pband:registry=https://git.pband.ch/api/packages/typescript/npm/
npm install @pband/global@1.0.1-rc.4
"@pband/global": "1.0.1-rc.4"

About this package

global

Values that outlive a module: a database pool, a mailer, a captured console. They live on globalThis, so a dev-server restart, which evaluates every module again, finds them instead of opening a second pool. Each app or library has its own namespace, typed by its own interface, and sees no one else's.

import {namespace} from '@pband/global'

interface Registry {
  DB: DB
  config: Config
}
export const global = namespace<Registry>('feezio')

global.set('DB', await connect())
global.get('DB') // DB

Install

Published as @pband/global on a Gitea npm registry; no account or token is needed. Map the scope in your app's .npmrc, then install it:

@pband:registry=https://git.pband.ch/api/packages/typescript/npm/
bun add @pband/global

Release candidates are published under the rc tag: bun add @pband/global@rc.

ESM only, with type declarations; runs on Node and Bun.

Namespaces

namespace<R>(name) returns get, tryGet and set for the keys of R. Call it once, in one module, and export what it returns.

  • The name is your package name: feezio for an app, @pband/log for a library. Two calls with the same name reach the same values; that is how a restart finds them again, and how two installed copies of a library share one state.
  • Isolation is by name. An app doesn't see a library's keys, nor a library the app's, as long as each uses its own name. Nothing stops a consumer from opening another's namespace on purpose: the name has to be stable to survive a restart, so it can't be a secret.

Unset and null

A key is unset until a value is set for it.

  • get(key) returns the value, and throws when the key is unset: global: "DB" is not set in namespace "feezio". Use it for what startup always sets.

  • tryGet(key) returns the value or undefined. Use it for what may not be set yet, like starting something once per process:

    if (global.tryGet('purge') === undefined) global.set('purge', setInterval(purge, HOUR))
    
  • To record that something is deliberately absent, declare the key T | null and set null: tryGet then tells null (absent) from undefined (not initialized yet). Setting undefined makes a key unset again.

Dependencies

Development Dependencies

ID Version
@eslint/js ^10.0.1
@types/bun ^1.4.3
eslint ^10.13.0
jiti ^2.7.0
prettier ^3.9.10
typescript ^6.0.3
typescript-eslint ^8.71.2
Details
npm
2026-11-09 11:11:14 +01:00
1
Pascal Perrenoud <pascal@pband.ch>
MIT
2.8 KiB
Assets (1)
Versions (4) View all
1.0.1-rc.5 2026-11-09
1.0.1-rc.4 2026-11-09
1.0.0 2026-10-18
0.1.0-rc.1 2026-10-18