@pband/global (1.0.1-rc.5)
Installation
@pband:registry=https://git.pband.ch/api/packages/typescript/npm/npm install @pband/global@1.0.1-rc.5"@pband/global": "1.0.1-rc.5"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:
feeziofor an app,@pband/logfor 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 orundefined. 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 | nulland setnull:tryGetthen tellsnull(absent) fromundefined(not initialized yet). Settingundefinedmakes 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 |