1. API reference
  2. @samveys/flags

@samveys/flags

OpenFeature-compatible feature flags with a database provider

Version
1.0.3Nov 5, 2026
Install
pnpm add @samveys/flags

This list was read from version 1.0.2; run pnpm sync to refresh it.

Import 
import { bucketOf, createDatabaseFlagProvider, createFlagClient, flags, inRollout, resolveFlag } from '@samveys/flags'

Function (6)

bucketOf Function

The rollout bucket of a user for a flag: the first 4 bytes of SHA-256(`flagKey:targetingKey`) read as an unsigned big-endian integer, modulo 100. Pure and stable: the same pair gives the same bucket in every process, on every machine and in every release.

function bucketOf(flagKey: string, targetingKey: string): number;

Exported from packages/flags/src/bucket.ts

createDatabaseFlagProvider Function

Flags in a SQL table: `samveys_feature_flags(key, enabled, rollout_percent, variants JSON, rules JSON)`. The table is created on first use. Rows are read on every evaluation, so a change in the table takes effect immediately in every process.

function createDatabaseFlagProvider(options: DatabaseProviderOptions): DatabaseFlagProvider;

Exported from packages/flags/src/database-provider.ts

createFlagClient Function

Creates the evaluation client over any provider. Evaluation never throws: failures return the default with `reason: 'ERROR'`.

function createFlagClient(provider: FlagProvider, defaultContext?: EvaluationContext): FlagClient;

Exported from packages/flags/src/client.ts

flags Function

The `@samveys/flags` plugin: binds `'flags'`. Without a `provider` it reads the `samveys_feature_flags` table of the `'db'` binding.

function flags(config?: FlagsConfig): import("@samveys/core").Plugin<FlagsConfig>;

Exported from packages/flags/src/plugin.ts

inRollout Function

True when the user falls inside a rollout of `percent` percent.

function inRollout(flagKey: string, targetingKey: string, percent: number): boolean;

Exported from packages/flags/src/bucket.ts

resolveFlag Function

Picks the variant for one evaluation. Pure: no I/O, so it is easy to test and the same everywhere.

function resolveFlag<T>(flag: FlagRecord, kind: Kind, defaultValue: T, context: EvaluationContext): EvaluationDetails<T>;

Exported from packages/flags/src/evaluate.ts

Interface (9)

DatabaseFlagProvider Interface

The built-in provider also manages definitions.

interface DatabaseFlagProvider extends FlagProvider {
    /** Creates or replaces a flag definition. */
    save(flag: Partial<FlagRecord> & {
        readonly key: string;
    }): Promise<FlagRecord>;
    delete(key: string): Promise<void>;
}

Exported from packages/flags/src/contracts.ts

DatabaseProviderOptions Interface

No documentation comment.

interface DatabaseProviderOptions {
    /** The connection; resolved on first use. */
    readonly database: () => Database;

Exported from packages/flags/src/contracts.ts

EvaluationContext Interface

Who or what the flag is evaluated for. `targetingKey` (a user id, for example) drives rollouts.

interface EvaluationContext {
    readonly targetingKey?: string;
    readonly [attribute: string]: unknown;
}

Exported from packages/flags/src/contracts.ts

EvaluationDetails Interface

The result of one evaluation (OpenFeature `ResolutionDetails` plus the flag key).

interface EvaluationDetails<T> {
    readonly flagKey: string;
    readonly value: T;
    readonly variant?: string;
    readonly reason: EvaluationReason;
    readonly errorCode?: ErrorCode;
    readonly errorMessage?: string;
}

Exported from packages/flags/src/contracts.ts

FlagClient Interface

OpenFeature-style client.

interface FlagClient {
    getBooleanValue(key: string, defaultValue: boolean, context?: EvaluationContext): Promise<boolean>;
    getStringValue(key: string, defaultValue: string, context?: EvaluationContext): Promise<string>;
    getNumberValue(key: string, defaultValue: number, context?: EvaluationContext): Promise<number>;
    getObjectValue<T extends object>(key: string, defaultValue: T, context?: EvaluationContext): Promise<T>;
    getBooleanDetails(key: string, defaultValue: boolean, context?: EvaluationContext): Promise<EvaluationDetails<boolean>>;
    getStringDetails(key: string, defaultValue: string, context?: EvaluationContext): Promise<EvaluationDetails<string>>;
    getNumberDetails(key: string, defaultValue: number, context?: EvaluationContext): Promise<EvaluationDetails<number>>;
    getObjectDetails<T extends object>(key: string, defaultValue: T, context?: EvaluationContext): Promise<EvaluationDetails<T>>;
}

Exported from packages/flags/src/contracts.ts

FlagProvider Interface

Where flag definitions come from.

interface FlagProvider {
    /** The definition of `key`, or `undefined` when it does not exist. */
    find(key: string): Promise<FlagRecord | undefined>;
}

Exported from packages/flags/src/contracts.ts

FlagRecord Interface

One row of `samveys_feature_flags`. Evaluation order: not `enabled` → DISABLED (the caller's default); the first matching `rules` entry → its variant; `rolloutPercent` 100 → `on` for everyone; otherwise the user's stable bucket decides between `on` and `off`. `variants` maps variant names to values; `on` and `off` default to `true` and `false` for boolean flags.

interface FlagRecord {
    readonly key: string;
    readonly enabled: boolean;
    /** 0–100. */
    readonly rolloutPercent: number;
    readonly variants: Readonly<Record<string, unknown>>;
    readonly rules: readonly FlagRule[];
}

Exported from packages/flags/src/contracts.ts

FlagRule Interface

One targeting rule: when `attribute` of the context satisfies `operator`/`value`, serve `variant`.

interface FlagRule {
    readonly attribute: string;
    readonly operator: RuleOperator;
    readonly value: unknown;
    readonly variant: string;
}

Exported from packages/flags/src/contracts.ts

FlagsConfig Interface

No documentation comment.

interface FlagsConfig {
    /** Default: the built-in database provider on the `'db'` binding. */
    readonly provider?: FlagProvider;
    /** Context merged under every evaluation's own context (environment, app version, …). */
    readonly defaultContext?: EvaluationContext;
    /** Table of the built-in provider. Default `samveys_feature_flags`. */
    readonly table?: string;
}

Exported from packages/flags/src/contracts.ts

Type (3)

ErrorCode Type

No documentation comment.

type ErrorCode = 'FLAG_NOT_FOUND' | 'TYPE_MISMATCH' | 'TARGETING_KEY_MISSING' | 'PARSE_ERROR' | 'GENERAL';

Exported from packages/flags/src/contracts.ts

EvaluationReason Type

Why a value was returned (OpenFeature reasons).

type EvaluationReason = 'STATIC' | 'DEFAULT' | 'TARGETING_MATCH' | 'SPLIT' | 'DISABLED' | 'ERROR';

Exported from packages/flags/src/contracts.ts

RuleOperator Type

No documentation comment.

type RuleOperator = 'equals' | 'notEquals' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte';

Exported from packages/flags/src/contracts.ts