dataforge

The module returned by require "@dataforge".

local dataforge = require "@dataforge"

Functions

dataforge.create_store(config)

function dataforge.create_store<T>(config: Config<T>): Store<T>

Creates a Store over the datastore named config.name. See Store config for every field.

Throws if name or template is missing.

dataforge.transaction(profiles, process, config?)

function dataforge.transaction(
	profiles: { ProfileBase },
	process: (ctx: TxContext) -> boolean?,
	config: TransactionConfig?
): Result<boolean>

Atomically updates any set of profiles, across stores and mixing locked and lockless ones. process reads with ctx:get(profile) and stages writes with ctx:set(profile, new); return false to cancel (nothing is written).

• Ok(false) when cancelled, Ok(true) when committed.
• Fails with tx_aborted (its cause says which participant failed and why), profile_closed, released, or what flushing a lockless participant raised. See Errors.
• Throws on misuse (non-profiles, duplicates, no profiles, mixed hooks, ctx:set(profile, nil)) and when process throws.
• config defaults its retry settings to the first profile's.

See Transactions.

dataforge.is_error(value)

function dataforge.is_error(value: any): boolean

Whether value is a dataforge Error table — what a failed Result carries and what the library throws internally. Use it in your own pcall wrappers to tell a library error from any other thrown value:

local ok, err = pcall(function()
	return store:load(key, {}):unwrap()
end)
if not ok and dataforge.is_error(err) then
	warn(`dataforge {err.type}: {err.message}`)
end

dataforge.result

The Result helpers, so you can build library-shaped results in your own wrappers.

Function	Description
result.ok(value)	Ok(value).
result.err(error)	Err(error). Asserts that error is a dataforge Error, so a malformed result cannot be built.
result.is(value)	Whether value is a Result.
result.of(ok, value)	A pcall outcome as a Result: Ok when ok, Err when value is an Error, rethrown otherwise.
result.capture(fn, ...)	pcall(fn, ...) folded through of.

Namespaces

dataforge.hooks and dataforge.schedulers hold the storage and time backends used to run the library outside Roblox. See Hooks.

Exported types

export type Store<T = any>
export type Config<T = any>
export type TransactionConfig
export type TxContext
export type Profile<T = any>
export type LocklessProfile<T = any>
export type ProfileBase<T = any>
export type PeekProfile<T = any>
export type Result<T>
export type Error
export type Migration
export type DataDispatcher<T = any>

See Types.