@playstack/entitlements
Source-projected boolean capabilities and numeric limits with explicit subject enforcement.
Reference: @playstack/entitlements@0.1.0-beta.5 · TypeScript
Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.
@playstack/entitlements projects grants from billing, licensing, registration, staff, or another authority into stable capabilities and limits. It does not own plans, prices, authentication, feature flags, or provider side effects.
const registry = defineEntitlements({
'packages.pro': { kind: 'boolean' },
'tokens.maximum': { kind: 'number' },
})
const entitlements = createEntitlements({
registry,
persistence,
events,
clock,
ids,
})
await entitlements.replaceSource({
subject: { type: 'account', id: accountId },
source: { type: 'stripe', id: subscriptionId },
grants: [{ entitlement: 'packages.pro', value: true }],
})
const decisions = await entitlements.resolveMany(
{ type: 'account', id: accountId },
['packages.pro', 'tokens.maximum'],
)
const snapshot = await entitlements.snapshot({
type: 'account',
id: accountId,
})Boolean grants combine with OR and numeric grants by maximum. Replacing one source affects only that projection; replacing it with no grants revokes it. The package emits transactional entitlements.grants.replaced events and publishes an ejectable Prisma fragment plus @playstack/entitlements/prisma.
Both bulk reads use one persistence lookup rather than querying once per
entitlement. replaceSourceInTransaction() lets Billing or another
same-database authority update grants on an existing transaction. It verifies
the transaction kind and emits the ordinary grants-replaced event on that unit
of work; separate stores use the normal idempotent source replacement path.
The explicit resolveInTransaction, resolveManyInTransaction,
snapshotInTransaction, hasAllInTransaction and assertAllInTransaction
methods accept the same subject/names followed by the caller's physical
transaction. They read its uncommitted grants using one persistence lookup and
evaluate time bounds after that read, without a nested transaction. They capture
the original subject, names and handle before waits. Native guards reject known
root, wrong-kind and completed handles; custom adapters must implement
assertTransaction and honor list(subject, transaction?) rather than reading
their root client. The published scaffold and conformance checks cover that change;
no schema migration is required.
Grant decisions are not identity proof or an authorization lease. The caller's isolation level controls visibility, and later waits may change authority or expiry. Keep read-dependent writes on the same transaction, propagate failures and expose results only after the outer commit.
Install
After confirming preview access, install the package at your application's shared Playstack version:
npm install --save-exact @playstack/entitlements@0.1.0-beta.5Check the peer requirements below before choosing a runtime or provider.
API entry points and requirements
Reference snapshot: @playstack/entitlements@0.1.0-beta.5. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.
| Public entry point | Declaration file |
|---|---|
@playstack/entitlements | ./dist/index.d.ts |
@playstack/entitlements/errors | ./dist/errors.d.ts |
@playstack/entitlements/prisma | ./dist/prisma.d.ts |
@playstack/entitlements/testing | ./dist/testing.d.ts |
@playstack/entitlements/package.json | No TypeScript declaration (asset or metadata export). |
Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.
Peer dependencies
This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.
For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.