@stacksjs/feature-flags 0.70.90

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @stacksjs/feature-flags
+
+Typed, scoped feature flags for Stacks applications. The API follows the useful parts of Laravel Pennant while keeping storage and scope handling explicit for TypeScript.
+
+```ts
+import { Feature, percentage, variants } from '@stacksjs/feature-flags'
+
+Feature.define('new-checkout', percentage(10))
+Feature.define('search-layout', variants({ control: 50, compact: 30, visual: 20 }))
+Feature.define('team-reports', team => team.plan === 'pro')
+
+if (await Feature.for(user).active('new-checkout')) {
+  // Render the new checkout.
+}
+
+const layout = await Feature.value('search-layout', user)
+```
+
+Scopes are type-aware. Stacks ORM instances use their model definition and ID automatically. Plain objects with an `id` should provide `featureFlagType` when IDs can overlap across domain types:
+
+```ts
+await Feature.for({ id: account.id, featureFlagType: 'Account' }).active('team-reports')
+```
+
+Resolved values are sticky per scope. The first evaluation is stored by the configured driver and reused until it is changed or forgotten.
+
+```ts
+await Feature.for(user).activate('new-checkout')
+await Feature.for(user).deactivate('new-checkout')
+await Feature.for(user).forget('new-checkout') // evaluate its definition again
+await Feature.purge('new-checkout') // forget it for every scope
+```
+
+## Configuration
+
+`config/feature-flags.ts` selects the global facade's driver:
+
+```ts
+import { defineFeatureFlags } from '@stacksjs/config'
+
+export default defineFeatureFlags({
+  default: 'database',
+  missing: 'false',
+  drivers: {
+    memory: { cloneValues: true },
+    database: { table: 'feature_flags', autoCreate: false },
+  },
+})
+```
+
+The schema belongs to this package. It never writes into an application's `database/migrations` directory implicitly. Applications can explicitly provision it, opt into lazy creation, or publish the generated SQL through their own migration workflow:
+
+```ts
+import { db } from '@stacksjs/database'
+import { ensureFeatureFlagTable, featureFlagMigrationSql } from '@stacksjs/feature-flags'
+
+await ensureFeatureFlagTable(db, { dialect: 'sqlite', table: 'feature_flags' })
+const statements = featureFlagMigrationSql({ dialect: 'postgres' })
+```
+
+Set `autoCreate: true` only when runtime DDL is appropriate for the application. Production applications will usually publish `featureFlagMigrationSql()` into their migration workflow and leave automatic creation disabled.
+
+Use an isolated manager in tests:
+
+```ts
+import { createFeatureFlags } from '@stacksjs/feature-flags'
+
+const flags = createFeatureFlags()
+flags.define({ checkout: true, recommendations: false })
+```

package/dist/drivers/database.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseFeatureFlagDriverOptions, FeatureDatabaseClient, FeatureDriver, FeatureValue } from '../types';
+export declare function createDatabaseFeatureFlagDriver(database: FeatureDatabaseClient, options?: DatabaseFeatureFlagDriverOptions): DatabaseFeatureFlagDriver;
+export declare class DatabaseFeatureFlagDriver implements FeatureDriver {
+  readonly table: string;
+  constructor(database: FeatureDatabaseClient, options?: DatabaseFeatureFlagDriverOptions);
+  get(name: string, scopeKey: string): Promise<FeatureValue | undefined>;
+  set(name: string, scopeKey: string, value: FeatureValue): Promise<void>;
+  delete(name: string, scopeKey: string): Promise<void>;
+  deleteForAllScopes(names?: readonly string[]): Promise<void>;
+  clear(): Promise<void>;
+  stored(scopeKey: string): Promise<Record<string, FeatureValue>>;
+}

package/dist/drivers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './database';
+export * from './memory';

package/dist/drivers/memory.d.ts

@@ -0,0 +1,14 @@
+import type { FeatureDriver, FeatureValue } from '../types';
+export declare function createMemoryFeatureFlagDriver(options?: MemoryFeatureFlagDriverOptions): MemoryFeatureFlagDriver;
+export declare interface MemoryFeatureFlagDriverOptions {
+  cloneValues?: boolean
+}
+export declare class MemoryFeatureFlagDriver implements FeatureDriver {
+  constructor(options?: MemoryFeatureFlagDriverOptions);
+  get(name: string, scopeKey: string): Promise<FeatureValue | undefined>;
+  set(name: string, scopeKey: string, value: FeatureValue): Promise<void>;
+  delete(name: string, scopeKey: string): Promise<void>;
+  deleteForAllScopes(names?: readonly string[]): Promise<void>;
+  clear(): Promise<void>;
+  stored(scopeKey: string): Promise<Record<string, FeatureValue>>;
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class FeatureFlagError extends Error {
+  name: string;
+}
+export declare class FeatureNotDefinedError extends FeatureFlagError {
+  name: string;
+  constructor(feature: string);
+}
+export declare class InvalidFeatureValueError extends FeatureFlagError {
+  name: string;
+  constructor(message: string);
+}
+export declare class InvalidFeatureScopeError extends FeatureFlagError {
+  name: string;
+}
+export declare class FeatureFlagStoreError extends FeatureFlagError {
+  name: string;
+  constructor(message: string, options?: ErrorOptions);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+declare function configuredDriver(config: FeatureFlagsConfig, dialect: string | undefined): Promise<FeatureDriver>;
+/**
+ * Global, configuration-aware feature facade.
+ *
+ * The config and database imports stay lazy so defining flags at application
+ * boot cannot create a config/database module cycle.
+ */
+export declare const Feature: FeatureFlagManager;
+export declare const featureFlags: unknown;
+export * from './drivers/index';
+export * from './errors';
+export * from './manager';
+export * from './schema';
+export * from './scope';
+export * from './strategies';
+export * from './types';
+export * from './value';

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+var T=import.meta.require;class B extends Error{name="FeatureFlagError"}class q extends B{name="FeatureNotDefinedError";constructor(P){super(`Feature flag '${P}' has not been defined.`)}}class Y extends B{name="InvalidFeatureValueError";constructor(P){super(`Feature values must be JSON-safe. ${P}`)}}class X extends B{name="InvalidFeatureScopeError"}class Z extends B{name="FeatureFlagStoreError";constructor(P,M){super(P,M)}}function V(P){if(P===void 0)throw new Y("Undefined is not a valid feature value.");if(typeof P==="number"&&!Number.isFinite(P))throw new Y("NaN and Infinity are not valid feature values.");if(typeof P==="bigint"||typeof P==="function"||typeof P==="symbol")throw new Y(`Values of type '${typeof P}' are not supported.`);try{let M=JSON.stringify(P);if(M===void 0)throw new Y("The value cannot be serialized.");return JSON.parse(M)}catch(M){if(M instanceof Y)throw M;throw new Y(M instanceof Error?M.message:String(M))}}function O(P="feature_flags"){if(!/^[A-Za-z_][A-Za-z0-9_]*$/.test(P))throw new Z(`Invalid feature flag table name '${P}'.`);return P}function F(P={}){let M=O(P.table),$=P.dialect??"sqlite";if($==="mysql")return[`CREATE TABLE IF NOT EXISTS ${M} (name VARCHAR(191) NOT NULL,scope VARCHAR(512) NOT NULL,value TEXT NOT NULL,created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,UNIQUE KEY ${M}_name_scope_unique (name, scope),KEY ${M}_scope_index (scope))`];let J=$==="postgres"?"TIMESTAMPTZ":"DATETIME";return[`CREATE TABLE IF NOT EXISTS ${M} (name VARCHAR(191) NOT NULL,scope VARCHAR(512) NOT NULL,value TEXT NOT NULL,created_at ${J} DEFAULT CURRENT_TIMESTAMP,updated_at ${J} DEFAULT CURRENT_TIMESTAMP,UNIQUE (name, scope))`,`CREATE INDEX IF NOT EXISTS ${M}_scope_index ON ${M}(scope)`]}async function g(P,M){if(!P.unsafe)throw new Z("The database client does not support schema provisioning via unsafe SQL.");let $=P.unsafe(M);if($&&typeof $.execute==="function")await $.execute();else await $}async function D(P,M={}){for(let $ of F(M))await g(P,$)}function f(P){return JSON.stringify(V(P))}function S(P){try{return V(JSON.parse(P.value))}catch(M){throw new Z(`Stored value for feature '${P.name}' is invalid JSON.`,{cause:M})}}function K(P){let M=P,$=M?.message??"";return M?.code==="23505"||M?.code==="ER_DUP_ENTRY"||/unique constraint|duplicate entry/i.test($)}class C{database;table;ready;constructor(P,M={}){this.database=P;this.table=O(M.table),this.ready=M.autoCreate?D(P,{table:this.table,dialect:M.dialect}):Promise.resolve()}async get(P,M){await this.ready;let $=await this.database.selectFrom(this.table).where("name","=",P).where("scope","=",M).select(["name","value"]).executeTakeFirst();return $?S($):void 0}async set(P,M,$){await this.ready;let J=f($),L=new Date().toISOString();if(await this.database.selectFrom(this.table).where("name","=",P).where("scope","=",M).select(["name"]).executeTakeFirst()){await this.update(P,M,J,L);return}try{await this.database.insertInto(this.table).values({name:P,scope:M,value:J,created_at:L,updated_at:L}).execute()}catch(W){if(!K(W))throw W;await this.update(P,M,J,L)}}async update(P,M,$,J){await this.database.updateTable(this.table).set({value:$,updated_at:J}).where("name","=",P).where("scope","=",M).execute()}async delete(P,M){await this.ready,await this.database.deleteFrom(this.table).where("name","=",P).where("scope","=",M).execute()}async deleteForAllScopes(P){if(await this.ready,!P){await this.clear();return}for(let M of new Set(P))await this.database.deleteFrom(this.table).where("name","=",M).execute()}async clear(){await this.ready,await this.database.deleteFrom(this.table).execute()}async stored(P){await this.ready;let M=await this.database.selectFrom(this.table).where("scope","=",P).select(["name","value"]).execute(),$={};for(let J of M)Object.defineProperty($,J.name,{value:S(J),enumerable:!0,configurable:!0,writable:!0});return $}}function a(P,M){return new C(P,M)}class R{values=new Map;cloneValues;constructor(P={}){this.cloneValues=P.cloneValues??!0}clone(P){return this.cloneValues?V(P):P}async get(P,M){let $=this.values.get(M)?.get(P);return $===void 0?void 0:this.clone($)}async set(P,M,$){let J=this.values.get(M);if(!J)J=new Map,this.values.set(M,J);J.set(P,this.clone($))}async delete(P,M){let $=this.values.get(M);if($?.delete(P),$?.size===0)this.values.delete(M)}async deleteForAllScopes(P){if(!P){this.values.clear();return}let M=new Set(P);for(let[$,J]of this.values){for(let L of M)J.delete(L);if(J.size===0)this.values.delete($)}}async clear(){this.values.clear()}async stored(P){let M={};for(let[$,J]of this.values.get(P)??[])Object.defineProperty(M,$,{value:this.clone(J),enumerable:!0,configurable:!0,writable:!0});return M}}function MP(P){return new R(P)}import{createHash as b}from"crypto";function U(P){if(new TextEncoder().encode(P).byteLength<=512)return P;return`sha256:${b("sha256").update(P).digest("hex")}`}function A(P,M){if(P===null||typeof P!=="object"){if(typeof P==="bigint")return{$bigint:P.toString()};if(typeof P==="symbol"||typeof P==="function"||P===void 0)throw new X(`Feature scope contains unsupported value '${typeof P}'.`);if(typeof P==="number"&&!Number.isFinite(P))throw new X("Feature scope cannot contain NaN or Infinity.");return P}if(M.has(P))throw new X("Feature scope cannot contain circular references.");M.add(P);try{if(P instanceof Date)return{$date:P.toISOString()};if(Array.isArray(P))return P.map((L)=>A(L,M));let $=Object.getPrototypeOf(P);if($!==Object.prototype&&$!==null)throw new X("Feature scope objects must be plain objects or expose featureFlagScope.");let J={};for(let L of Object.keys(P).sort())J[L]=A(P[L],M);return J}finally{M.delete(P)}}function y(P){return typeof P.featureFlagScope==="function"?P.featureFlagScope():P.featureFlagScope}function d(P){return(typeof P.featureFlagType==="function"?P.featureFlagType():P.featureFlagType)?.trim()||P.constructor?.name||"object"}function u(P,M){let $=typeof P.featureFlagType==="function"?P.featureFlagType():P.featureFlagType;if(typeof $==="string"&&$.trim())return $.trim();let J=P._definition;if(J&&typeof J==="object"){let L=J.name;if(typeof L==="string"&&L.trim())return L.trim()}return M.constructor?.name||"object"}function k(P){if(P===null||P===void 0)return"global";if(typeof P==="string")return U(`string:${P}`);if(typeof P==="number"){if(!Number.isFinite(P))throw new X("Feature scope cannot be NaN or Infinity.");return`number:${P}`}if(typeof P==="bigint")return`bigint:${P}`;if(typeof P==="boolean")return`boolean:${P}`;if(typeof P==="symbol"||typeof P==="function")throw new X(`Feature scope of type '${typeof P}' is not supported.`);let M=P;if("featureFlagScope"in M){let $=M,J=y($);if(typeof J!=="string"&&typeof J!=="number"||String(J).length===0)throw new X("featureFlagScope must resolve to a non-empty string or number.");return U(`model:${d($)}:${String(J)}`)}if("id"in M&&(typeof M.id==="string"||typeof M.id==="number")){let $=u(M,P);return U(`model:${$}:${String(M.id)}`)}return U(`object:${JSON.stringify(A(P,new WeakSet))}`)}function _(P){if(typeof P!=="string"||P.trim().length===0)throw TypeError("Feature flag names must be non-empty strings.");if(P!==P.trim())throw TypeError("Feature flag names cannot start or end with whitespace.");if(new TextEncoder().encode(P).byteLength>191)throw TypeError("Feature flag names cannot exceed 191 UTF-8 bytes.");return P}function E(P,M){return JSON.stringify([P,M])}function h(P){return typeof P==="function"?P:V(P)}function N(P,M,$){Object.defineProperty(P,M,{value:$,enumerable:!0,configurable:!0,writable:!0})}class I{manager;scope;constructor(P,M){this.manager=P;this.scope=M}value(P){return this.manager.value(P,this.scope)}values(P){return this.manager.values(P,this.scope)}all(){return this.manager.all(this.scope)}active(P){return this.manager.active(P,this.scope)}inactive(P){return this.manager.inactive(P,this.scope)}activate(P,M=!0){return this.manager.activate(P,M,this.scope)}deactivate(P){return this.manager.deactivate(P,this.scope)}forget(P){return this.manager.forget(P,this.scope)}when(P,M,$){return this.manager.when(P,M,$,this.scope)}unless(P,M,$){return this.manager.unless(P,M,$,this.scope)}}class x{definitions=new Map;pending=new Map;listeners=new Set;resolveScope;driverSource;driverPromise;missingBehavior;constructor(P={}){this.driverSource=P.driver??new R,this.missingBehavior=P.missing??"false",this.resolveScope=P.scopeResolver??k}use(P){return this.driverSource=P,this.driverPromise=void 0,this.pending.clear(),this}missing(P){return this.missingBehavior=P,this}define(P,M){if(typeof P==="string"){if(M===void 0)throw TypeError(`A definition is required for feature '${P}'.`);return this.definitions.set(_(P),h(M)),this}for(let[$,J]of Object.entries(P))this.definitions.set(_($),h(J));return this}defined(P){return this.definitions.has(_(P))}definedNames(){return[...this.definitions.keys()]}clearDefinitions(){return this.definitions.clear(),this}for(P){return new I(this,P)}async value(P,M=null){let $=_(P),J=this.resolveScope(M),L=E($,J),Q=this.pending.get(L);if(Q)return Q;let W=this.evaluate($,M,J);this.pending.set(L,W);try{return await W}finally{if(this.pending.get(L)===W)this.pending.delete(L)}}async evaluate(P,M,$){let J=await this.driver(),L=await J.get(P,$);if(L!==void 0){let G=V(L);return await this.notify({name:P,scope:M,scopeKey:$,value:G,source:"stored"}),G}let Q=this.definitions.get(P);if(Q===void 0){if(this.missingBehavior==="throw")throw new q(P);let G=!1;return await this.notify({name:P,scope:M,scopeKey:$,value:G,source:"missing"}),G}let W=typeof Q==="function"?await Q(M,{name:P,scope:M,scopeKey:$}):Q,H=V(W);return await J.set(P,$,H),await this.notify({name:P,scope:M,scopeKey:$,value:H,source:"resolver"}),H}async values(P,M=null){let $=[...new Set(P.map(_))],J=await Promise.all($.map(async(L)=>[L,await this.value(L,M)]));return Object.fromEntries(J)}async all(P=null){let M=this.resolveScope(P),$=await(await this.driver()).stored(M),J={};for(let[L,Q]of Object.entries($))N(J,L,V(Q));for(let L of this.definitions.keys())if(!Object.hasOwn(J,L))N(J,L,await this.value(L,P));return J}async active(P,M=null){return Boolean(await this.value(P,M))}async inactive(P,M=null){return!await this.active(P,M)}async activate(P,M=!0,$=null){let J=_(P),L=this.resolveScope($);await this.awaitPending(J,L),await(await this.driver()).set(J,L,V(M))}deactivate(P,M=null){return this.activate(P,!1,M)}async forget(P,M=null){let $=_(P),J=this.resolveScope(M);await this.awaitPending($,J),await(await this.driver()).delete($,J)}async purge(P){let M=P===void 0?void 0:(Array.isArray(P)?P:[P]).map(_);await Promise.allSettled(this.pending.values()),await(await this.driver()).deleteForAllScopes(M)}async flush(){await Promise.allSettled(this.pending.values()),await(await this.driver()).clear()}async when(P,M,$,J=null){let L=await this.value(P,J);return Boolean(L)?M(L):$?.(L)}async unless(P,M,$,J=null){let L=await this.value(P,J);return Boolean(L)?$?.(L):M(L)}onEvaluated(P){return this.listeners.add(P),()=>this.listeners.delete(P)}async notify(P){await Promise.allSettled([...this.listeners].map((M)=>Promise.resolve().then(()=>M(P))))}async awaitPending(P,M){let $=this.pending.get(E(P,M));if($)try{await $}catch{}}driver(){if(!this.driverPromise){let P=Promise.resolve(typeof this.driverSource==="function"?this.driverSource():this.driverSource);this.driverPromise=P,P.catch(()=>{if(this.driverPromise===P)this.driverPromise=void 0})}return this.driverPromise}}function ZP(P){return new x(P)}function v(P){if(!Number.isFinite(P)||P<0||P>100)throw RangeError(`Percentage must be between 0 and 100. Received ${P}.`)}function j(P){let M=new TextEncoder().encode(P),$=2166136261;for(let J of M)$^=J,$=Math.imul($,16777619);return($>>>0)/4294967296*100}function GP(P){return v(P),(M,$)=>j(`${$.name}\x00${$.scopeKey}`)<P}function HP(P){let M=Object.entries(P),$=M[M.length-1];if(!$)throw RangeError("At least one feature variant is required.");let J=0;for(let[L,Q]of M){if(!Number.isFinite(Q)||Q<=0)throw RangeError(`Variant '${L}' must have a positive, finite weight.`);J+=Q}return(L,Q)=>{let W=j(`${Q.name}\x00${Q.scopeKey}`)/100*J,H=0;for(let[G,z]of M)if(H+=z,W<H)return G;return $[0]}}async function m(P,M){if(P.default==="database"){if(M!=="sqlite"&&M!=="mysql"&&M!=="singlestore"&&M!=="postgres")throw new Z(`The feature flag database driver requires a SQL database. Received '${M??"undefined"}'.`);let{db:$}=await import("@stacksjs/database");return new C($,{...P.drivers?.database,dialect:M==="mysql"||M==="singlestore"?"mysql":M==="postgres"?"postgres":"sqlite"})}return new R(P.drivers?.memory)}var w=new x({driver:async()=>{let{awaitConfig:P}=await import("@stacksjs/config"),M=await P();return w.missing(M.featureFlags.missing??"false"),m(M.featureFlags,M.database.default)}}),qP=w;export{HP as variants,GP as percentage,V as normalizeFeatureValue,k as featureScopeKey,qP as featureFlags,O as featureFlagTableName,F as featureFlagMigrationSql,j as featureBucket,D as ensureFeatureFlagTable,MP as createMemoryFeatureFlagDriver,ZP as createFeatureFlags,a as createDatabaseFeatureFlagDriver,I as ScopedFeatureFlags,R as MemoryFeatureFlagDriver,Y as InvalidFeatureValueError,X as InvalidFeatureScopeError,q as FeatureNotDefinedError,Z as FeatureFlagStoreError,x as FeatureFlagManager,B as FeatureFlagError,w as Feature,C as DatabaseFeatureFlagDriver};

package/dist/manager.d.ts

@@ -0,0 +1,42 @@
+import type { FeatureDefinition, FeatureDriver, FeatureDriverFactory, FeatureEvaluation, FeatureFlagManagerOptions, FeatureScope, FeatureValue } from './types';
+export declare function createFeatureFlags(options?: FeatureFlagManagerOptions): FeatureFlagManager;
+declare type EvaluationListener = (evaluation: FeatureEvaluation) => void | Promise<void>;
+export declare class ScopedFeatureFlags<Scope = FeatureScope> {
+  readonly scope: Scope;
+  constructor(manager: FeatureFlagManager, scope: Scope);
+  value(name: string): Promise<FeatureValue>;
+  values(names: readonly string[]): Promise<Record<string, FeatureValue>>;
+  all(): Promise<Record<string, FeatureValue>>;
+  active(name: string): Promise<boolean>;
+  inactive(name: string): Promise<boolean>;
+  activate(name: string, value?: FeatureValue): Promise<void>;
+  deactivate(name: string): Promise<void>;
+  forget(name: string): Promise<void>;
+  when<Active, Inactive = undefined>(name: string, onActive: (value: FeatureValue) => Active | Promise<Active>, onInactive?: (value: FeatureValue) => Inactive | Promise<Inactive>): Promise<Active | Inactive | undefined>;
+  unless<Inactive, Active = undefined>(name: string, onInactive: (value: FeatureValue) => Inactive | Promise<Inactive>, onActive?: (value: FeatureValue) => Active | Promise<Active>): Promise<Inactive | Active | undefined>;
+}
+export declare class FeatureFlagManager {
+  constructor(options?: FeatureFlagManagerOptions);
+  use(driver: FeatureDriver | FeatureDriverFactory): this;
+  missing(behavior: 'false' | 'throw'): this;
+  define<Scope = FeatureScope>(name: string, definition: FeatureDefinition<Scope>): this;
+  define(definitions: Record<string, FeatureDefinition>): this;
+  define<Scope = FeatureScope>(nameOrDefinitions: string | Record<string, FeatureDefinition>, definition?: FeatureDefinition<Scope>): this;
+  defined(name: string): boolean;
+  definedNames(): string[];
+  clearDefinitions(): this;
+  for<Scope>(scope: Scope): ScopedFeatureFlags<Scope>;
+  value(name: string, scope?: FeatureScope): Promise<FeatureValue>;
+  values(names: readonly string[], scope?: FeatureScope): Promise<Record<string, FeatureValue>>;
+  all(scope?: FeatureScope): Promise<Record<string, FeatureValue>>;
+  active(name: string, scope?: FeatureScope): Promise<boolean>;
+  inactive(name: string, scope?: FeatureScope): Promise<boolean>;
+  activate(name: string, value?: FeatureValue, scope?: FeatureScope): Promise<void>;
+  deactivate(name: string, scope?: FeatureScope): Promise<void>;
+  forget(name: string, scope?: FeatureScope): Promise<void>;
+  purge(names?: string | readonly string[]): Promise<void>;
+  flush(): Promise<void>;
+  when<Active, Inactive = undefined>(name: string, onActive: (value: FeatureValue) => Active | Promise<Active>, onInactive?: (value: FeatureValue) => Inactive | Promise<Inactive>, scope?: FeatureScope): Promise<Active | Inactive | undefined>;
+  unless<Inactive, Active = undefined>(name: string, onInactive: (value: FeatureValue) => Inactive | Promise<Inactive>, onActive?: (value: FeatureValue) => Active | Promise<Active>, scope?: FeatureScope): Promise<Inactive | Active | undefined>;
+  onEvaluated(listener: EvaluationListener): () => void;
+}

package/dist/schema.d.ts

@@ -0,0 +1,14 @@
+import type { FeatureDatabaseClient } from './types';
+export declare function featureFlagTableName(table?: string): string;
+/**
+ * Return the package-owned schema for publishing or explicit provisioning.
+ * No application migration file is written implicitly.
+ */
+export declare function featureFlagMigrationSql(options?: FeatureFlagSchemaOptions): string[];
+/** Explicitly provision the feature flag table using the package-owned schema. */
+export declare function ensureFeatureFlagTable(database: FeatureDatabaseClient, options?: FeatureFlagSchemaOptions): Promise<void>;
+export declare interface FeatureFlagSchemaOptions {
+  table?: string
+  dialect?: FeatureFlagSqlDialect
+}
+export type FeatureFlagSqlDialect = 'sqlite' | 'mysql' | 'postgres';

package/dist/scope.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureScope } from './types';
+/** Convert a scope into a stable, type-aware storage key. */
+export declare function featureScopeKey(scope: FeatureScope): string;

package/dist/strategies.d.ts

@@ -0,0 +1,7 @@
+import type { FeatureResolver } from './types';
+/** Stable FNV-1a hash normalized to the half-open range [0, 100). */
+export declare function featureBucket(input: string): number;
+/** Deterministically activate a percentage of scopes for a flag. */
+export declare function percentage(percent: number): FeatureResolver;
+/** Deterministically assign every scope to one weighted variant. */
+export declare function variants<const Name extends string>(weights: Record<Name, number>): FeatureResolver<unknown>;

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export declare interface FeatureScopeKeyProvider {
+  featureFlagScope: string | number | (() => string | number)
+  featureFlagType?: string | (() => string)
+}
+export declare interface FeatureContext<Scope = FeatureScope> {
+  name: string
+  scope: Scope
+  scopeKey: string
+}
+export declare interface FeatureEvaluation<Scope = FeatureScope> extends FeatureContext<Scope> {
+  value: FeatureValue
+  source: FeatureEvaluationSource
+}
+export declare interface FeatureDriver {
+  get: (name: string, scopeKey: string) => Promise<FeatureValue | undefined>
+  set: (name: string, scopeKey: string, value: FeatureValue) => Promise<void>
+  delete: (name: string, scopeKey: string) => Promise<void>
+  deleteForAllScopes: (names?: readonly string[]) => Promise<void>
+  clear: () => Promise<void>
+  stored: (scopeKey: string) => Promise<Record<string, FeatureValue>>
+}
+export declare interface FeatureFlagManagerOptions {
+  driver?: FeatureDriver | FeatureDriverFactory
+  missing?: 'false' | 'throw'
+  scopeResolver?: (scope: FeatureScope) => string
+}
+export declare interface DatabaseFeatureFlagDriverOptions {
+  table?: string
+  autoCreate?: boolean
+  dialect?: 'sqlite' | 'mysql' | 'postgres'
+}
+export declare interface FeatureDatabaseClient {
+  selectFrom: (table: string) => any
+  insertInto: (table: string) => any
+  updateTable: (table: string) => any
+  deleteFrom: (table: string) => any
+  unsafe?: (sql: string) => any
+}
+export type FeatureScalar = boolean | string | number | null;
+export type FeatureValue = | FeatureScalar
+  | { [key: string]: FeatureValue }
+  | FeatureValue[];
+export type FeatureScope = unknown;
+export type FeatureResolver<Scope = FeatureScope> = (
+  scope: Scope,
+  context: FeatureContext<Scope>,
+) => FeatureValue | Promise<FeatureValue>;
+export type FeatureDefinition<Scope = FeatureScope> = FeatureValue | FeatureResolver<Scope>;
+export type FeatureEvaluationSource = 'stored' | 'resolver' | 'missing';
+export type FeatureDriverFactory = () => FeatureDriver | Promise<FeatureDriver>;

package/dist/value.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureValue } from './types';
+/** Validate and detach a feature value so every driver has identical semantics. */
+export declare function normalizeFeatureValue(value: unknown): FeatureValue;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@stacksjs/feature-flags",
+  "type": "module",
+  "sideEffects": false,
+  "version": "0.70.90",
+  "description": "Typed, scoped feature flags for Stacks applications.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/feature-flags#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/feature-flags"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "feature-flags",
+    "rollout",
+    "experiments",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "development": "./src/*",
+      "bun": "./dist/*",
+      "import": "./dist/*",
+      "default": "./dist/*"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "test": "bun test",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@stacksjs/config": "0.70.90",
+    "@stacksjs/database": "0.70.90",
+    "@stacksjs/query-builder": "0.70.90",
+    "better-dx": "^0.2.16"
+  }
+}