@rbxts/dataforge 0.1.0 → 0.2.0

package/index.d.ts

@@ -197,6 +197,172 @@ declare namespace dataforge {
 
 	type TxOutcome = "committed" | "aborted";
 
+	/*
+		Errors and results
+	*/
+
+	interface ErrorBase {
+		readonly type: string;
+		/** Human readable; `tostring(err)` returns it. */
+		readonly message: string;
+	}
+
+	/** Storage kept failing after `retry_attempts`. */
+	interface RobloxError extends ErrorBase {
+		readonly type: "roblox";
+		readonly op: "get_async" | "update_async";
+		readonly store: string;
+		readonly key: string;
+		/** The last raw error the storage hook threw. */
+		readonly cause: unknown;
+	}
+
+	/** `load` / `readquire` gave up after `load_timeout`. */
+	interface TimeoutError extends ErrorBase {
+		readonly type: "timeout";
+		readonly key: string;
+		/** The last lock seen on the record (its holder). */
+		readonly lock: Lock | undefined;
+	}
+
+	/** A write found the session lock is not ours; the profile is closed. */
+	interface LockLostError extends ErrorBase {
+		readonly type: "lock_lost";
+		readonly profile: Profile<any>;
+		/** The lock now on the record, `undefined` when it was wiped. */
+		readonly lock: Lock | undefined;
+	}
+
+	/** The profile was released and not readquired. */
+	interface ReleasedError extends ErrorBase {
+		readonly type: "released";
+		readonly profile: Profile<any>;
+	}
+
+	/** Another server holds a live session lock on a lockless key; the profile is closed. */
+	interface LocklessLockedError extends ErrorBase {
+		readonly type: "lockless_locked";
+		readonly profile: LocklessProfile<any>;
+		readonly lock: Lock;
+	}
+
+	/** The transaction lock a lockless participant held is gone or replaced; the profile is closed. */
+	interface TxLockLostError extends ErrorBase {
+		readonly type: "tx_lock_lost";
+		readonly profile: LocklessProfile<any>;
+		/** The transaction lock this profile held. */
+		readonly expected: Lock;
+		/** The lock now on the record, `undefined` when none. */
+		readonly lock: Lock | undefined;
+	}
+
+	/**
+	 * The record was written by a newer server (it lists more migrations than
+	 * this store declares). Nothing is written and no lock is taken.
+	 */
+	interface OutdatedError extends ErrorBase {
+		readonly type: "outdated";
+		readonly key: string;
+		/** The profile the call ran on; `undefined` for `store.load` and `store.peek`. */
+		readonly profile: AnyProfile<any> | undefined;
+		readonly record_migrations: string[];
+		readonly declared_migrations: string[];
+	}
+
+	/** Lockless `get_data` before any fetch / flush. Thrown, never returned. */
+	interface NotFetchedError extends ErrorBase {
+		readonly type: "not_fetched";
+		readonly profile: LocklessProfile<any>;
+	}
+
+	/** The profile is closed (or closed while the call waited for it). */
+	interface ProfileClosedError extends ErrorBase {
+		readonly type: "profile_closed";
+		readonly profile: AnyProfile<any>;
+		readonly reason: "unloaded" | "lock_lost";
+	}
+
+	/**
+	 * A name in the record's applied migrations differs from the declared one
+	 * at `index`. A record with more migrations than declared is `outdated`.
+	 */
+	interface MigrationMismatchError extends ErrorBase {
+		readonly type: "migration_mismatch";
+		readonly key: string;
+		readonly index: number;
+		readonly expected: string;
+		readonly actual: string;
+		/** Names the record has applied / this store declares. */
+		readonly applied: string[];
+		readonly declared: string[];
+	}
+
+	/** The transaction aborted. */
+	interface TxAbortedError extends ErrorBase {
+		readonly type: "tx_aborted";
+		readonly id: string;
+		/**
+		 * The error of the participant that failed phase 1; `undefined` when
+		 * the marker was already resolved as aborted by another server.
+		 */
+		readonly cause: DataforgeError | undefined;
+	}
+
+	/** The marker datastore holds something other than "committed" / "aborted". */
+	interface TxMarkerInvalidError extends ErrorBase {
+		readonly type: "tx_marker_invalid";
+		readonly id: string;
+		readonly value: unknown;
+	}
+
+	interface StoreClosedError extends ErrorBase {
+		readonly type: "store_closed";
+		readonly store: Store<any>;
+	}
+
+	interface AlreadyLoadedError extends ErrorBase {
+		readonly type: "already_loaded";
+		readonly store: Store<any>;
+		readonly key: string;
+	}
+
+	/** Every runtime failure the library reports. Narrow on `type`. */
+	type DataforgeError =
+		| RobloxError
+		| TimeoutError
+		| LockLostError
+		| ReleasedError
+		| LocklessLockedError
+		| TxLockLostError
+		| OutdatedError
+		| NotFetchedError
+		| ProfileClosedError
+		| MigrationMismatchError
+		| TxAbortedError
+		| TxMarkerInvalidError
+		| StoreClosedError
+		| AlreadyLoadedError;
+
+	interface Ok<T> {
+		readonly success: true;
+		readonly value: T;
+		/** Returns `value`. */
+		unwrap(): T;
+	}
+
+	interface Err {
+		readonly success: false;
+		readonly error: DataforgeError;
+		/** Throws `error` (the table itself). */
+		unwrap(): never;
+	}
+
+	/**
+	 * What every fallible call returns. Programmer errors (bad config, misuse
+	 * of a transaction) and errors thrown by your own callbacks still throw.
+	 */
+	type Result<T> = Ok<T> | Err;
+
 	/*
 		Profiles
 	*/
@@ -216,16 +382,22 @@ declare namespace dataforge {
 		readonly open: boolean;
 		readonly migrations: string[];
 
-		/** Current data. Throws if the profile is closed or (lockless) not fetched. */
+		/**
+		 * Current data. A plain accessor: throws a `DataforgeError`
+		 * (`profile_closed`, or `not_fetched` for a lockless profile).
+		 */
 		get_data(): T;
-		save(): void;
+		/** Fails with `profile_closed`, `released`, `roblox`, `lock_lost` (locked) or `lockless_locked`, `outdated`, ... (lockless). */
+		save(): Result<void>;
 		unload(): void;
 		/**
 		 * Applies `dispatcher` to the current data. Returning `undefined` or
-		 * `false` leaves the data untouched (returns `false`); anything else
-		 * becomes the new data and is persisted on the next save.
+		 * `false` leaves the data untouched (`Ok(false)`); anything else
+		 * becomes the new data and is persisted on the next save (`Ok(true)`).
+		 * Fails with `profile_closed` / `released`; an error thrown by the
+		 * dispatcher propagates as is.
 		 */
-		update(dispatcher: DataDispatcher<T>): boolean;
+		update(dispatcher: DataDispatcher<T>): Result<boolean>;
 
 		on_change(callback: (newData: T, oldData: T | undefined) => void): void;
 		on_save(callback: () => void): void;
@@ -255,8 +427,8 @@ declare namespace dataforge {
 		/**
 		 * Whether the profile currently holds its session lock. True after
 		 * `load`; `release` clears it, `readquire` takes it again. While
-		 * released, `update` / `save` throw and the profile cannot join a
-		 * transaction.
+		 * released, `update` / `save` fail with `released` and the profile
+		 * cannot join a transaction.
 		 */
 		readonly is_locked: boolean;
 
@@ -266,13 +438,15 @@ declare namespace dataforge {
 		/**
 		 * Writes the data and gives the session lock back, keeping the profile
 		 * open so another server may take the key. No-op when already released.
+		 * Fails with `profile_closed`, `roblox` or `lock_lost`.
 		 */
-		release(): void;
+		release(): Result<void>;
 		/**
 		 * Takes the session lock again (waits like `load` does) and adopts the
-		 * stored record as the current data. No-op when already locked.
+		 * stored record as the current data. No-op when already locked. Fails
+		 * with `timeout`, `profile_closed`, `roblox`, `outdated`, `migration_mismatch`.
 		 */
-		readquire(): void;
+		readquire(): Result<void>;
 	}
 
 	/** Profile without a session lock; updates are queued and folded into storage on save. */
@@ -286,9 +460,10 @@ declare namespace dataforge {
 		/**
 		 * Reads the stored record into the local data: migrations are applied,
 		 * then the queued updates replayed on top. Marks the profile fetched.
-		 * Yields. Throws (keeping the queue) if a session lock is on the record.
+		 * Yields. Fails (keeping the queue) with `lockless_locked` if a session
+		 * lock is on the record, `outdated`, `roblox`, `migration_mismatch`, `profile_closed`.
 		 */
-		fetch(): T;
+		fetch(): Result<T>;
 	}
 
 	/** Either profile kind; narrow on `kind`. */
@@ -310,8 +485,12 @@ declare namespace dataforge {
 		readonly migrations: string[];
 
 		get_data(): T;
-		/** Calls `GetAsync` again and replaces `lock`, `pending`, `migrations` and the data. Yields. */
-		refresh(): T;
+		/**
+		 * Calls `GetAsync` again and replaces `lock`, `pending`, `migrations`
+		 * and the data. Yields. Fails with `roblox`, `outdated` or `migration_mismatch`,
+		 * keeping the previous snapshot.
+		 */
+		refresh(): Result<T>;
 	}
 
 	/*
@@ -334,36 +513,46 @@ declare namespace dataforge {
 		readonly profiles: ReadonlyMap<string, Profile<T>>;
 		readonly lockless_profiles: ReadonlyMap<string, LocklessProfile<T>>;
 
-		/** Takes the session lock for `key` and loads it. Yields. Throws when already loaded. */
-		load(key: string, user_ids: number[]): Profile<T>;
-		/** Returns the profile for `key`, waiting for it to load or loading it if nobody has yet. */
-		wait_loaded(key: string, user_ids: number[]): Profile<T>;
+		/**
+		 * Takes the session lock for `key` and loads it. Yields. Fails with
+		 * `store_closed`, `already_loaded`, `timeout`, `roblox`,
+		 * `outdated`, `migration_mismatch` or `tx_marker_invalid`.
+		 */
+		load(key: string, user_ids: number[]): Result<Profile<T>>;
+		/**
+		 * Returns the profile for `key`, waiting for it to load or loading it
+		 * if nobody has yet. Waiters get the same result as the load.
+		 */
+		wait_loaded(key: string, user_ids: number[]): Result<Profile<T>>;
 		get_loaded(key: string): Profile<T> | undefined;
 
 		/**
 		 * Returns the lockless profile for `key`, creating it if needed. Never
 		 * yields: a lockless profile does no storage work until `fetch`.
+		 * Throws a `store_closed` error on a closed store.
 		 */
 		get_lockless(key: string, user_ids: number[]): LocklessProfile<T>;
 
 		/**
 		 * Read-only snapshot of `key` via `GetAsync`: the current data and lock.
 		 * Yields. The result is not tracked by the store, takes no lock and
-		 * cannot join a transaction.
+		 * cannot join a transaction. Fails with `store_closed`, `roblox`, `outdated`
+		 * or `migration_mismatch`.
 		 */
-		peek(key: string): PeekProfile<T>;
+		peek(key: string): Result<PeekProfile<T>>;
 
 		/**
 		 * Atomically updates profiles of this store (locked or lockless).
 		 * `transform` gets their data in order and returns the new data in the
-		 * same order, or `false` to cancel. Returns `false` when cancelled,
-		 * `true` when committed; throws when aborted.
+		 * same order, or `false` to cancel. `Ok(false)` when cancelled,
+		 * `Ok(true)` when committed; fails like `dataforge.transaction`, plus
+		 * `store_closed`.
 		 */
 		transaction(
 			profiles: ProfileBase<T>[],
 			transform: (data: T[]) => T[] | false,
 			config?: TransactionConfig,
-		): boolean;
+		): Result<boolean>;
 
 		on_change(callback: (profile: AnyProfile<T>, newData: T, oldData: T | undefined) => void): void;
 		on_save(callback: (profile: AnyProfile<T>) => void): void;
@@ -390,14 +579,17 @@ declare namespace dataforge {
 	 * and lockless ones. `process` reads with `ctx.get(profile)` and stages
 	 * writes with `ctx.set(profile, newData)`; return `false` to cancel.
 	 *
-	 * Returns `false` when cancelled, `true` when committed. Throws when aborted.
-	 * `config` defaults its retry settings to the first profile's.
+	 * `Ok(false)` when cancelled, `Ok(true)` when committed. Fails with
+	 * `tx_aborted` (see its `cause`), `profile_closed`, `released`, or what
+	 * flushing a lockless participant raised. Misuse and errors thrown by
+	 * `process` throw. `config` defaults its retry settings to the first
+	 * profile's.
 	 */
 	function transaction(
 		profiles: ProfileBase<any>[],
 		process: (ctx: TxContext) => boolean | undefined,
 		config?: TransactionConfig,
-	): boolean;
+	): Result<boolean>;
 
 	namespace hooks {
 		namespace memory {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/dataforge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Roblox DataStore library with cross-key transactions, session-locked and lockless profiles, migrations and an immutable data model.",
   "license": "MIT",
   "author": "PepeElToro41",

package/src/errors.luau

@@ -0,0 +1,195 @@
+--!strict
+
+local types = require "./types"
+
+--[[
+	Error tables. Every runtime failure the library reports is one of these:
+	a plain table with a `type`, a `message` and typed extra data, sharing one
+	metatable so `tostring(err)` yields the message and `errors.is` can tell
+	them apart from raw (string) errors thrown by user callbacks.
+]]
+
+type Array<T> = { T }
+type Lock = types.Lock
+
+local error_mt = {
+	__tostring = function(self: any): string
+		return self.message
+	end,
+}
+
+local function make<T>(fields: T): T
+	return setmetatable(fields :: any, error_mt) :: any
+end
+
+local errors = {}
+
+function errors.is(value: any): boolean
+	return type(value) == "table" and getmetatable(value) == error_mt
+end
+
+function errors.roblox(op: "get_async" | "update_async", store: string, key: string, cause: any): types.RobloxError
+	return make {
+		type = "roblox" :: "roblox",
+		message = `datastore: {op} on "{store}/{key}" failed after retries: {tostring(cause)}`,
+		op = op,
+		store = store,
+		key = key,
+		cause = cause,
+	}
+end
+
+function errors.timeout(key: string, lock: Lock?): types.TimeoutError
+	return make {
+		type = "timeout" :: "timeout",
+		message = `datastore: timed out loading "{key}" (session locked by another server)`,
+		key = key,
+		lock = lock,
+	}
+end
+
+function errors.lock_lost(profile: any, lock: Lock?): types.LockLostError
+	return make {
+		type = "lock_lost" :: "lock_lost",
+		message = `datastore: profile "{profile.key}" lost its session lock`,
+		profile = profile,
+		lock = lock,
+	}
+end
+
+function errors.released(profile: any): types.ReleasedError
+	return make {
+		type = "released" :: "released",
+		message = `datastore: profile "{profile.key}" is released (does not hold its session lock)`,
+		profile = profile,
+	}
+end
+
+function errors.lockless_locked(profile: any, lock: Lock): types.LocklessLockedError
+	return make {
+		type = "lockless_locked" :: "lockless_locked",
+		message = `datastore: lockless profile "{profile.key}" is session locked by another server`,
+		profile = profile,
+		lock = lock,
+	}
+end
+
+function errors.tx_lock_lost(profile: any, expected: Lock, lock: Lock?): types.TxLockLostError
+	return make {
+		type = "tx_lock_lost" :: "tx_lock_lost",
+		message = `datastore: transaction lock on "{profile.key}" was lost`,
+		profile = profile,
+		expected = expected,
+		lock = lock,
+	}
+end
+
+--- `profile` is the lockless / locked profile the call ran on, when there is
+--- one (nil for `load` and `peek`).
+function errors.outdated(
+	key: string,
+	record_migrations: Array<string>,
+	declared_migrations: Array<string>,
+	profile: any?
+): types.OutdatedError
+	return make {
+		type = "outdated" :: "outdated",
+		message = `datastore: "{key}" was written by a newer server (record has {#record_migrations} applied migrations, this server declares {#declared_migrations})`,
+		key = key,
+		profile = profile,
+		record_migrations = record_migrations,
+		declared_migrations = declared_migrations,
+	}
+end
+
+function errors.not_fetched(profile: any): types.NotFetchedError
+	return make {
+		type = "not_fetched" :: "not_fetched",
+		message = `datastore: lockless profile "{profile.key}" has not been fetched`,
+		profile = profile,
+	}
+end
+
+function errors.profile_closed(profile: any, reason: "unloaded" | "lock_lost"): types.ProfileClosedError
+	local message = if reason == "lock_lost"
+		then `datastore: profile "{profile.key}" is closed (lock lost)`
+		else `datastore: profile "{profile.key}" is closed`
+	return make {
+		type = "profile_closed" :: "profile_closed",
+		message = message,
+		profile = profile,
+		reason = reason,
+	}
+end
+
+--- The error a closed profile rejects calls with: the one its mutex was closed
+--- with (carries the right reason), or a plain "unloaded" while `unload` is
+--- still waiting for the mutex.
+function errors.closed(profile: any): types.ProfileClosedError
+	local closed = profile._mutex._closed
+	if closed ~= nil then
+		return closed
+	end
+	return errors.profile_closed(profile, "unloaded")
+end
+
+export type MigrationMismatchDetails = {
+	index: number,
+	expected: string,
+	actual: string,
+	applied: Array<string>,
+	declared: Array<string>,
+}
+
+function errors.migration_mismatch(key: string, details: MigrationMismatchDetails): types.MigrationMismatchError
+	local reason =
+		`migration mismatch at index {details.index}: record has "{details.actual}", declared is "{details.expected}"`
+	return make {
+		type = "migration_mismatch" :: "migration_mismatch",
+		message = `datastore: failed to apply migrations for "{key}": {reason}`,
+		key = key,
+		index = details.index,
+		expected = details.expected,
+		actual = details.actual,
+		applied = details.applied,
+		declared = details.declared,
+	}
+end
+
+function errors.tx_aborted(id: string, cause: types.Error?): types.TxAbortedError
+	local reason = if cause then (cause :: any).message else "marker resolved as aborted by another server"
+	return make {
+		type = "tx_aborted" :: "tx_aborted",
+		message = `datastore: transaction {id} aborted: {reason}`,
+		id = id,
+		cause = cause,
+	}
+end
+
+function errors.tx_marker_invalid(id: string, value: any): types.TxMarkerInvalidError
+	return make {
+		type = "tx_marker_invalid" :: "tx_marker_invalid",
+		message = `datastore: unexpected tx marker value for {id}: {tostring(value)}`,
+		id = id,
+		value = value,
+	}
+end
+
+function errors.store_closed(store: any): types.StoreClosedError
+	return make {
+		type = "store_closed" :: "store_closed",
+		message = `datastore: store "{store.config.name}" is closed`,
+		store = store,
+	}
+end
+
+function errors.already_loaded(store: any, key: string): types.AlreadyLoadedError
+	return make {
+		type = "already_loaded" :: "already_loaded",
+		message = `datastore: "{key}" is already loaded in this store`,
+		store = store,
+		key = key,
+	}
+end
+
+return errors

package/src/hooks/memory.luau

@@ -42,17 +42,6 @@ type Failure = {
 	message: string,
 }
 
-local HEX = "0123456789abcdef"
-
-function random_jobid(): string
-	local chars = table.create(16)
-	for index = 1, 16 do
-		local nibble = math.random(1, 16)
-		chars[index] = string.sub(HEX, nibble, nibble)
-	end
-	return table.concat(chars)
-end
-
 local memory = {}
 
 function memory.create(scheduler: types.Scheduler): MemoryHook
@@ -113,7 +102,7 @@ function memory.create(scheduler: types.Scheduler): MemoryHook
 	end
 
 	-- one id per hook instance: locks are owned by job id, so it must be stable
-	local job_id = random_jobid()
+	local job_id = utils.uuid()
 	function self.job_id()
 		return job_id
 	end

package/src/hooks/roblox.luau

@@ -2,6 +2,7 @@
 --!nolint UnknownGlobal
 
 local types = require "../types"
+local utils = require "../utils"
 
 --[[
 	DataStoreService hook. Only usable inside Roblox.
@@ -17,8 +18,16 @@ function roblox_hook.create(): types.Hook
 
 	self.warn = warn
 
+	-- `game.JobId` is an empty string in Studio, so every Studio session would
+	-- share the same lock owner and transaction id prefix. Generate a random
+	-- one once per hook instead; locks are owned by job id, so it must be stable.
+	local job_id: string = game.JobId
+	if job_id == "" then
+		job_id = `studio-{utils.uuid()}`
+	end
+
 	function self.job_id()
-		return game.JobId :: string
+		return job_id
 	end
 
 	function self.get_datastore(name: string): types.DatastoreHandle

package/src/init.luau

@@ -18,6 +18,8 @@ export type Profile<T = any> = types.Profile<T>
 export type LocklessProfile<T = any> = types.LocklessProfile<T>
 export type ProfileBase<T = any> = types.ProfileBase<T>
 export type PeekProfile<T = any> = types.PeekProfile<T>
+export type Result<T> = types.Result<T>
+export type Error = types.Error
 
 local dataforge = {}
 
@@ -26,12 +28,14 @@ function dataforge.create_store<T>(config: Config<T>): Store<T>
 end
 
 --- Atomically updates any set of profiles, across stores and mixing locked and
---- lockless ones.
+--- lockless ones. Ok(false) when `process` returns false, Ok(true) when
+--- committed. Fails with `tx_aborted` (see its `cause`), `profile_closed`,
+--- `released`, or what flushing a lockless participant raised.
 function dataforge.transaction(
 	profiles: Array<ProfileBase>,
 	process: (ctx: TxContext) -> boolean?,
 	config: TransactionConfig?
-): boolean
+): Result<boolean>
 	local first = profiles[1]
 	local defaults: TransactionConfig? = if first
 		then {

package/src/mutex.luau

@@ -24,7 +24,7 @@ end
 
 function mutex.lock(self: Mutex)
 	if self._closed then
-		error(self._closed, 2)
+		error(self._closed, 0)
 	end
 	if not self._locked then
 		self._locked = true
@@ -34,7 +34,7 @@ function mutex.lock(self: Mutex)
 	-- resumed with a reason only when the mutex was closed while waiting
 	local rejection = coroutine.yield()
 	if rejection ~= nil then
-		error(rejection, 2)
+		error(rejection, 0)
 	end
 end
 
@@ -59,9 +59,9 @@ function mutex.unlock(self: Mutex)
 	self.scheduler.spawn(next_waiter)
 end
 
---- Rejects every current and future lock with `reason`. Idempotent: a second
---- close keeps the first reason.
-function mutex.close(self: Mutex, reason: string)
+--- Rejects every current and future lock with `reason` (an `Error` table,
+--- thrown as is). Idempotent: a second close keeps the first reason.
+function mutex.close(self: Mutex, reason: any)
 	if self._closed then
 		return
 	end