Reading and Writing API

Core methods for getting, setting, and manipulating flag values.

get()

Retrieves the value of a flag.

Signature:

get(key: string): FlagValue | undefined

Parameters:

Returns: FlagValue | undefined — The flag value, or undefined if the flag doesn't exist.

Example:

store.set('gold', 100)
store.get('gold')      // 100
store.get('missing')   // undefined

set()

Sets a flag to a specific value.

Signature:

set(key: string, value: FlagValue | null | undefined): FlagStore

Parameters:

Returns: FlagStore — The store instance for chaining.

Throws:

• ValidationError — If the key is empty, contains spaces, or is a reserved word (AND, OR, NOT)
• TypeError — If the value is not boolean, number, or string
• Error — If attempting to set a computed flag

Example:

store.set('gold', 100)
store.set('name', 'Ada')
store.set('active', true)

// Chaining
store.set('a', 1).set('b', 2).set('c', 3)

// Delete by setting null/undefined
store.set('gold', null)

has()

Checks if a flag exists in the store.

Signature:

has(key: string): boolean

Parameters:

Returns: boolean — true if the flag exists, false otherwise.

Example:

store.set('gold', 100)
store.has('gold')      // true
store.has('missing')   // false

delete()

Deletes a flag from the store.

Signature:

delete(key: string): FlagStore

Parameters:

Returns: FlagStore — The store instance for chaining.

Throws:

• Error — If attempting to delete a computed flag

Example:

store.set('gold', 100)
store.delete('gold')
store.has('gold')      // false

clear()

Deletes all flags from the store.

Signature:

clear(): FlagStore

Returns: FlagStore — The store instance for chaining.

Example:

store.set('a', 1)
store.set('b', 2)
store.clear()
store.keys()           // []

Note: Computed flag definitions are preserved (but their values update based on cleared dependencies).

toggle()

Toggles a boolean flag.

Signature:

toggle(key: string): boolean

Parameters:

Returns: boolean — The new value after toggling.

Throws:

• ValidationError — If the key is invalid
• TypeError — If the flag exists and is not a boolean
• Error — If attempting to toggle a computed flag

Example:

store.set('dark_mode', false)
store.toggle('dark_mode')  // true
store.toggle('dark_mode')  // false

// Creates flag if missing (defaults to true)
store.toggle('new_flag')   // true

increment()

Increments a numeric flag by a specified amount.

Signature:

increment(key: string, amount?: number): number

Parameters:

Returns: number — The new value after incrementing.

Throws:

• ValidationError — If the key is invalid
• TypeError — If the flag exists and is not a number
• Error — If attempting to increment a computed flag

Example:

store.set('count', 10)
store.increment('count')      // 11
store.increment('count', 5)   // 16

// Creates flag if missing (initializes to amount)
store.increment('new', 100)   // 100

decrement()

Decrements a numeric flag by a specified amount.

Signature:

decrement(key: string, amount?: number): number

Parameters:

Returns: number — The new value after decrementing.

Throws:

• ValidationError — If the key is invalid
• TypeError — If the flag exists and is not a number
• Error — If attempting to decrement a computed flag

Example:

store.set('health', 100)
store.decrement('health')      // 99
store.decrement('health', 25)  // 74

// Creates flag if missing (initializes to -amount)
store.decrement('new', 5)      // -5

all()

Gets all flags in the store as a plain object.

Signature:

all(): Record<string, FlagValue>

Returns: Record<string, FlagValue> — An object with all flag keys and their values.

Example:

store.set('a', 1)
store.set('b', 'hello')
store.all()  // { a: 1, b: 'hello' }

keys()

Gets all flag keys in the store.

Signature:

keys(): string[]

Returns: string[] — An array of flag keys.

Example:

store.set('gold', 100)
store.set('level', 5)
store.keys()  // ['gold', 'level']

setMany()

Sets multiple flags at once.

Signature:

setMany(values: Record<string, FlagValue | null | undefined>): FlagStore

Parameters:

Returns: FlagStore — The store instance for chaining.

Throws:

• ValidationError — If any key is invalid
• TypeError — If any value type is not allowed

Example:

store.setMany({
  gold: 100,
  level: 5,
  name: 'Ada'
})

Note: All keys are validated before any values are set. If validation fails, no changes are made.