@prsm/entitle 2.0.0 → 2.1.1

package/README.md

@@ -91,6 +91,7 @@ const entitlements = createEntitlements({
   meter,
 })
 
+// account.id is assigned the "pro" plan, whose tokens limit is 5_000_000
 const quota = await entitlements.check(account.id, "tokens")
 // { allowed: true, used: 84210, remaining: 4915790, limit: 5000000, unit: "tokens", feature: "tokens" }
 
@@ -117,7 +118,7 @@ The **plan catalog** is declared once at construction, the way you declare your
 
 **Assignments** (which plan a subject is on) and **overrides** (per-subject adjustments) live in postgres and are mutable at runtime. An override shallow-merges over the plan, so you specify only what differs. A subject with no assignment gets `defaultPlan`; `unassign(subject)` removes an assignment and reverts the subject to the default (distinct from assigning the default explicitly, which would not follow a later change to `defaultPlan`).
 
-Overrides accumulate: each `override()` call merges into the subject's existing override rather than replacing it, so granting more seats and later enabling a feature leaves both in place, and overriding a key again updates just that key. `clearOverride(subject)` removes the whole override; `clearOverride(subject, { limits: ["seats"] })` reverts only the named keys and keeps the rest.
+Overrides accumulate: each `override()` call merges into the subject's existing override rather than replacing it, so granting more seats and later enabling a feature leaves both in place, and overriding a key again updates just that key. The merge happens in the database under a row lock, so two concurrent overrides to the same subject both land instead of one clobbering the other. `clearOverride(subject)` removes the whole override; `clearOverride(subject, { limits: ["seats"] })` reverts only the named keys and keeps the rest.
 
 ```js
 await entitlements.override(account.id, { limits: { seats: 50 } })
@@ -132,7 +133,7 @@ Resolved entitlements are cached per subject for a short, configurable window (`
 
 ### `createEntitlements({ driver, plans, defaultPlan, features?, limits?, meter?, cacheTtl?, tracer? })`
 
-Creates a resolver. `driver` is `postgresDriver({ pool })` or `memoryDriver()`. `plans` is the catalog; `defaultPlan` must be one of its keys. `features` and `limits` declare the universe of valid keys (defaulting to the union across plans); when given, plans may only reference declared keys. `meter` is an optional `@prsm/meter` instance, required only for `check()`. `cacheTtl` accepts ms or a string like `"10s"`. `tracer` is an optional `@prsm/trace` tracer.
+Creates a resolver. `driver` is `postgresDriver({ pool })` or `memoryDriver()`. `plans` is the catalog; `defaultPlan` must be one of its keys. `features` and `limits` declare the universe of valid keys (defaulting to the union across plans); when given, plans may only reference declared keys. `meter` is an optional `@prsm/meter` instance, required only for `check()`. `cacheTtl` accepts ms or a string like `"10s"`. `tracer` is an optional `@prsm/trace` tracer; `can()` and `check()` are wrapped in spans when it is present.
 
 ### `entitlements.setup()`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prsm/entitle",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Plan-based entitlements and feature gating, resolved at runtime, backed by postgres",
   "type": "module",
   "exports": {

package/src/entitlements.js

@@ -49,9 +49,13 @@ function assertBoolean(scope, key, v) {
 }
 
 function assertLimitValue(scope, key, v) {
-  if (v !== null && (typeof v !== "number" || !Number.isFinite(v))) {
+  if (v === null) return
+  if (typeof v !== "number" || !Number.isFinite(v)) {
     throw new Error(`${scope} limit "${key}" must be a finite number or null (null means unlimited)`)
   }
+  if (v < 0) {
+    throw new Error(`${scope} limit "${key}" must not be negative (use 0 to deny, null for unlimited)`)
+  }
 }
 
 /**
@@ -184,6 +188,12 @@ export function createEntitlements(options = {}) {
     return effective
   }
 
+  async function resolveLimit(subject, key) {
+    requireLimit(key)
+    const eff = await resolve(subject)
+    return key in eff.limits ? eff.limits[key] : 0
+  }
+
   return {
     /** Create the backing tables if they do not exist. Idempotent. */
     setup() {
@@ -226,11 +236,7 @@ export function createEntitlements(options = {}) {
     async override(subject, data) {
       if (!subject) throw new Error("override requires a `subject`")
       validateOverride(data, featureUniverse, limitUniverse)
-      const current = (await driver.getState(subject))?.override ?? {}
-      await driver.setOverride(subject, {
-        features: { ...(current.features ?? {}), ...(data.features ?? {}) },
-        limits: { ...(current.limits ?? {}), ...(data.limits ?? {}) },
-      })
+      await driver.mergeOverride(subject, { features: data.features ?? {}, limits: data.limits ?? {} })
       cache.invalidate(subject)
     },
 
@@ -245,20 +251,8 @@ export function createEntitlements(options = {}) {
       if (!subject) throw new Error("clearOverride requires a `subject`")
       if (!keys) {
         await driver.clearOverride(subject)
-        cache.invalidate(subject)
-        return
-      }
-      const current = (await driver.getState(subject))?.override
-      if (current) {
-        const features = { ...(current.features ?? {}) }
-        const limits = { ...(current.limits ?? {}) }
-        for (const k of keys.features ?? []) delete features[k]
-        for (const k of keys.limits ?? []) delete limits[k]
-        if (Object.keys(features).length === 0 && Object.keys(limits).length === 0) {
-          await driver.clearOverride(subject)
-        } else {
-          await driver.setOverride(subject, { features, limits })
-        }
+      } else {
+        await driver.removeOverrideKeys(subject, { features: keys.features ?? [], limits: keys.limits ?? [] })
       }
       cache.invalidate(subject)
     },
@@ -298,10 +292,8 @@ export function createEntitlements(options = {}) {
      * @param {string} key
      * @returns {Promise<number|null>}
      */
-    async limit(subject, key) {
-      requireLimit(key)
-      const eff = await resolve(subject)
-      return key in eff.limits ? eff.limits[key] : 0
+    limit(subject, key) {
+      return resolveLimit(subject, key)
     },
 
     /**
@@ -319,7 +311,7 @@ export function createEntitlements(options = {}) {
         throw new Error("check requires a `meter`; pass it to createEntitlements, or use limit() for the static ceiling")
       }
       return traced(tracer, "entitle.check", { "entitle.subject": subject, "entitle.feature": key }, async () => {
-        const limit = await this.limit(subject, key)
+        const limit = await resolveLimit(subject, key)
         const usage = await meter.usage({ ...usageQuery, subject, metric: key })
         const used = usage.quantity
         const allowed = limit === null || used < limit

package/src/memoryDriver.js

@@ -27,8 +27,22 @@ export function memoryDriver() {
       assignments.delete(subject)
     },
 
-    async setOverride(subject, data) {
-      overrides.set(subject, data)
+    async mergeOverride(subject, delta) {
+      const current = overrides.get(subject) ?? { features: {}, limits: {} }
+      overrides.set(subject, {
+        features: { ...(current.features ?? {}), ...(delta.features ?? {}) },
+        limits: { ...(current.limits ?? {}), ...(delta.limits ?? {}) },
+      })
+    },
+
+    async removeOverrideKeys(subject, keys) {
+      const current = overrides.get(subject)
+      if (!current) return
+      const features = { ...(current.features ?? {}) }
+      const limits = { ...(current.limits ?? {}) }
+      for (const k of keys.features ?? []) delete features[k]
+      for (const k of keys.limits ?? []) delete limits[k]
+      overrides.set(subject, { features, limits })
     },
 
     async clearOverride(subject) {

package/src/postgresDriver.js

@@ -56,11 +56,30 @@ export function postgresDriver(options = {}) {
       await pool.query(`delete from ${assignments} where subject = $1`, [subject])
     },
 
-    async setOverride(subject, data) {
+    async mergeOverride(subject, delta) {
       await pool.query(
-        `insert into ${overrides} (subject, data) values ($1, $2)
-         on conflict (subject) do update set data = excluded.data, updated_at = now()`,
-        [subject, JSON.stringify(data)],
+        `insert into ${overrides} (subject, data)
+         values ($1, jsonb_build_object('features', $2::jsonb, 'limits', $3::jsonb))
+         on conflict (subject) do update set
+           data = jsonb_build_object(
+             'features', coalesce(${overrides}.data -> 'features', '{}'::jsonb) || (excluded.data -> 'features'),
+             'limits',   coalesce(${overrides}.data -> 'limits',   '{}'::jsonb) || (excluded.data -> 'limits')
+           ),
+           updated_at = now()`,
+        [subject, JSON.stringify(delta.features ?? {}), JSON.stringify(delta.limits ?? {})],
+      )
+    },
+
+    async removeOverrideKeys(subject, keys) {
+      await pool.query(
+        `update ${overrides} set
+           data = jsonb_build_object(
+             'features', coalesce(data -> 'features', '{}'::jsonb) - $2::text[],
+             'limits',   coalesce(data -> 'limits',   '{}'::jsonb) - $3::text[]
+           ),
+           updated_at = now()
+         where subject = $1`,
+        [subject, keys.features ?? [], keys.limits ?? []],
       )
     },