@rbxts/dataforge 0.1.0 → 0.4.1

package/src/errors.luau

@@ -0,0 +1,211 @@
+--!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.predicate_failed(
+	key: string,
+	op: "load" | "save" | "fetch" | "peek",
+	data: any,
+	profile: any?
+): types.PredicateFailedError
+	return make {
+		type = "predicate_failed" :: "predicate_failed",
+		message = `datastore: the store predicate rejected the stored data of "{key}" (on {op})`,
+		key = key,
+		op = op,
+		data = data,
+		profile = profile,
+	}
+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

@@ -1,3 +1,5 @@
+local errors = require "@self/errors"
+local result = require "@self/result"
 local store = require "@self/store"
 local tx = require "@self/tx/handle"
 local types = require "@self/types"
@@ -18,6 +20,10 @@ 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
+export type Migration = types.Migration
+export type DataDispatcher<T = any> = types.DataDispatcher<T>
 
 local dataforge = {}
 
@@ -26,12 +32,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 {
@@ -45,6 +53,16 @@ function dataforge.transaction(
 	return tx.run(tx.resolve_config(config, defaults), profiles, process)
 end
 
+--- Whether `value` is a dataforge `Error` table (what a failed Result carries
+--- and what the library throws internally). Lets a wrapper around library calls
+--- tell a library error from any other thrown value.
+dataforge.is_error = errors.is
+
+--- The `Result` helpers (`ok`, `err`, `is`, `of`, `capture`), so a game can
+--- build library-shaped results in its own wrappers. `result.err` only accepts
+--- an `Error`, so a malformed result cannot be fabricated with it.
+dataforge.result = result
+
 dataforge.hooks = {
 	memory = memory_hook,
 	roblox = roblox_hook,

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

package/src/profile/common.luau

@@ -1,3 +1,4 @@
+local errors = require "../errors"
 local types = require "../types"
 
 type Array<T> = { T }
@@ -8,25 +9,33 @@ export type MigrationsResult = types.MigrationsResult
 
 local common = {}
 
---- Throws right away when the profile is closed, Its not necessary to add this, as it will get rejected either way,
---- by the mutex, but its used to throw instantly.
+--- Throws a `profile_closed` error right away when the profile is closed. Not
+--- strictly needed (the closed mutex rejects the call anyway) but it fails
+--- before queueing on the mutex.
 function common.assert_open(self: ProfileBase)
 	if not self.open then
-		error(`datastore: profile "{self.key}" is closed`, 3)
+		error(errors.closed(self), 0)
 	end
 end
 
 --- Applies the declared migrations not yet in `applied` (in order). Pure, so it
---- is safe inside an update transform. Fails when the record's applied list does
---- not prefix-match the declared list.
-function common.apply_migrations(data: any, applied: { string }, migrations: Array<types.Migration>): MigrationsResult
+--- is safe inside an update transform. Fails with `outdated` in `err` when the
+--- record lists more migrations than declared (a newer server wrote it), or
+--- `migration_mismatch` when a name in the applied prefix differs. An error
+--- thrown by a migration's `apply` propagates as is.
+function common.apply_migrations(
+	key: string,
+	data: any,
+	applied: { string },
+	migrations: Array<types.Migration>
+): MigrationsResult
 	local applied_count = #applied
 
 	if applied_count > #migrations then
 		return {
 			applied = false,
 			success = false,
-			err = `record has {applied_count} applied migrations but only {#migrations} are declared`,
+			err = errors.outdated(key, applied, common.all_migration_names(migrations)),
 			new_migrations = applied,
 		}
 	end
@@ -38,7 +47,13 @@ function common.apply_migrations(data: any, applied: { string }, migrations: Arr
 			return {
 				applied = false,
 				success = false,
-				err = `migration mismatch at index {index}: record has "{actual}", declared is "{expected}"`,
+				err = errors.migration_mismatch(key, {
+					index = index,
+					expected = expected,
+					actual = actual,
+					applied = applied,
+					declared = common.all_migration_names(migrations),
+				}),
 				new_migrations = applied,
 			}
 		end
@@ -67,7 +82,39 @@ function common.all_migration_names(migrations: Array<types.Migration>): { strin
 	return names
 end
 
-function common.is_lock_owned(record: types.DataRecord?, job_id: string)
+--- Whether the record lists more migrations than this server declares. Pure.
+function common.is_outdated(record: types.DataRecord?, config: types.ResolvedConfig): boolean
+	if not record or not record.migrations then
+		return false
+	end
+	return #record.migrations > #config.migrations
+end
+
+function common.run_predicate(config: types.ResolvedConfig, key: string, data: any): (boolean, any?)
+	local predicate = config.predicate
+	if predicate == nil then
+		return true, nil
+	end
+	local ok, passed = pcall(predicate, data, key)
+	if not ok then
+		return false, passed
+	end
+	return not not passed, nil
+end
+
+--- Rethrows a failed `apply_migrations` with the profile attached to an
+--- `outdated` error (a `migration_mismatch` has no profile field).
+function common.raise_migrations(profile: ProfileBase, migrated: MigrationsResult)
+	local err: any = migrated.err
+	if err.type == "outdated" then
+		err.profile = profile
+	end
+	error(err, 0)
+end
+
+--- Whether `lock_id` (the id of one acquisition) is the lock currently on
+--- the record, so this acquisition may write it.
+function common.is_lock_owned(record: types.DataRecord?, lock_id: string)
 	if not record then
 		return false
 	end
@@ -77,10 +124,12 @@ function common.is_lock_owned(record: types.DataRecord?, job_id: string)
 		return false
 	end
 
-	return lock.id == job_id
+	return lock.id == lock_id
 end
 
-function common.is_locked_for(record: types.DataRecord?, job_id: string, now: number)
+--- Whether a live lock of another acquisition holds the record, in which case
+--- `lock_id` must wait it out or steal it once it expires.
+function common.is_locked_for(record: types.DataRecord?, lock_id: string, now: number)
 	if not record then
 		return false
 	end
@@ -89,7 +138,7 @@ function common.is_locked_for(record: types.DataRecord?, job_id: string, now: nu
 		return false
 	end
 
-	return lock.id ~= job_id and lock.expires > now
+	return lock.id ~= lock_id and lock.expires > now
 end
 
 function common.has_lock(record: types.DataRecord?)