@rbxts/dataforge 0.1.0 → 0.4.1

package/src/types.luau

@@ -5,6 +5,17 @@ export type Counter = () -> number
 --- Returns the new data, or nil / false to leave it untouched.
 export type DataDispatcher<T> = (T) -> (T | false)?
 
+--- Decides whether this server may work with a key at all. `data` is the raw
+--- stored data as it is in storage: nil when the key does not exist yet, and
+--- with the declared migrations *not* applied. Returning false rejects the
+--- operation with a `predicate_failed` error: no lock is taken and nothing is
+--- written.
+---
+--- It runs inside the `update_async` transform, so it must be pure: no
+--- yielding, no storage calls, and no mutation of `data` (it may be retried,
+--- and the data it gets is the record this server is about to write back).
+export type Predicate<T = any> = (data: T?, key: string) -> boolean
+
 --- A storage handle for one named store. Deliberately not shaped like a
 --- Roblox DataStore. All methods throw on failure.
 export type DatastoreHandle = {
@@ -45,6 +56,10 @@ export type Config<T = any> = {
 
 	migrations: Array<Migration>?,
 
+	--- Gate on a key's stored data: every load, save, fetch and peek is
+	--- rejected with `predicate_failed` when it returns false. See `Predicate`.
+	predicate: Predicate<T>?,
+
 	--- seconds, default 30 (locked profiles)
 	autosave_interval: number?,
 	-- seconds, default autosave_interval (lockless profiles)
@@ -61,7 +76,7 @@ export type Config<T = any> = {
 	retry_base: number?,
 }
 
---- Options shared by the retry helper. Both `ResolvedConfig` and
+--- Options shared by the storage retry helpers. Both `ResolvedConfig` and
 --- `ResolvedTransactionConfig` satisfy it.
 export type RetryConfig = {
 	_scheduler: Scheduler,
@@ -77,6 +92,8 @@ export type ResolvedConfig<T = any> = RetryConfig & {
 	_scheduler: Scheduler,
 
 	migrations: Array<Migration>,
+	--- nil when the store declared none (nothing is gated).
+	predicate: Predicate<T>?,
 
 	autosave_interval: number,
 	flush_interval: number,
@@ -115,6 +132,10 @@ export type ResolvedTransactionConfig = RetryConfig & {
 }
 
 export type Lock = {
+	--- Identifies the *acquisition* that holds the lock, not the server:
+	--- `{job_id}#{n}` for a profile's session lock, `{job_id}-{n}` for a
+	--- transaction's. Two sessions of one key on the same server hold
+	--- different ids, so they contend like sessions on different servers do.
 	id: string,
 	expires: number,
 	--- Short-lived lock a transaction takes on a lockless key (see `lock_ttl`
@@ -139,10 +160,191 @@ export type DataRecord<T = any> = {
 	migrations: { string },
 }
 
+--[[
+	Errors and results
+]]
+
+--- Every runtime failure is one of these tables (see `errors.luau`): `type`
+--- tells them apart, `message` is human readable (`tostring(err)` returns
+--- it), the rest is typed extra data. `profile` / `store` fields are typed
+--- `any` on purpose: naming `ProfileBase` or `Store` here would put them in a
+--- recursive generic group with `Result`, which Luau rejects.
+export type RobloxError = {
+	type: "roblox",
+	message: string,
+	op: "get_async" | "update_async",
+	store: string,
+	key: string,
+	--- the last raw error the storage hook threw
+	cause: any,
+}
+
+export type TimeoutError = {
+	type: "timeout",
+	message: string,
+	key: string,
+	--- the last lock seen on the record while waiting; its `id` names the
+	--- acquisition holding it, which may be another session on this server
+	lock: Lock?,
+}
+
+export type LockLostError = {
+	type: "lock_lost",
+	message: string,
+	profile: any,
+	--- the lock now on the record, nil when it has none
+	lock: Lock?,
+}
+
+export type ReleasedError = {
+	type: "released",
+	message: string,
+	profile: any,
+}
+
+export type LocklessLockedError = {
+	type: "lockless_locked",
+	message: string,
+	profile: any,
+	--- the live session lock another server holds on the record
+	lock: Lock,
+}
+
+export type TxLockLostError = {
+	type: "tx_lock_lost",
+	message: string,
+	profile: any,
+	--- the transaction lock this profile held
+	expected: Lock,
+	--- the lock now on the record, nil when it has none
+	lock: Lock?,
+}
+
+--- The record lists more migrations than this server declares: a newer server
+--- wrote it, so this one must not touch it (nothing is written, no lock taken).
+export type OutdatedError = {
+	type: "outdated",
+	message: string,
+	key: string,
+	--- the profile the call ran on; nil for `store:load` and `store:peek`
+	profile: any?,
+	record_migrations: Array<string>,
+	declared_migrations: Array<string>,
+}
+
+--- The store's `predicate` returned false for a key's stored data: this server
+--- must not work with that key. Nothing is written and no lock is taken.
+export type PredicateFailedError = {
+	type: "predicate_failed",
+	message: string,
+	key: string,
+	--- the operation the predicate rejected
+	op: "load" | "save" | "fetch" | "peek",
+	--- the raw stored data the predicate rejected (nil when the key is empty)
+	data: any,
+	--- the profile the call ran on; nil for `store:load` and `store:peek`
+	profile: any?,
+}
+
+export type NotFetchedError = {
+	type: "not_fetched",
+	message: string,
+	profile: any,
+}
+
+export type ProfileClosedError = {
+	type: "profile_closed",
+	message: string,
+	profile: any,
+	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`.
+export type MigrationMismatchError = {
+	type: "migration_mismatch",
+	message: string,
+	key: string,
+	--- the position that differs, and the declared / record's name there
+	index: number,
+	expected: string,
+	actual: string,
+	--- names the record has applied / this server declares
+	applied: Array<string>,
+	declared: Array<string>,
+}
+
+export type TxAbortedError = {
+	type: "tx_aborted",
+	message: string,
+	id: string,
+	--- the failure that made phase 1 give up; nil when the marker was already
+	--- resolved as aborted by another server
+	cause: Error?,
+}
+
+export type TxMarkerInvalidError = {
+	type: "tx_marker_invalid",
+	message: string,
+	id: string,
+	value: any,
+}
+
+export type StoreClosedError = {
+	type: "store_closed",
+	message: string,
+	store: any,
+}
+
+export type AlreadyLoadedError = {
+	type: "already_loaded",
+	message: string,
+	store: any,
+	key: string,
+}
+
+export type Error =
+	| RobloxError
+	| TimeoutError
+	| LockLostError
+	| ReleasedError
+	| LocklessLockedError
+	| TxLockLostError
+	| OutdatedError
+	| PredicateFailedError
+	| NotFetchedError
+	| ProfileClosedError
+	| MigrationMismatchError
+	| TxAbortedError
+	| TxMarkerInvalidError
+	| StoreClosedError
+	| AlreadyLoadedError
+
+export type Ok<T> = {
+	success: true,
+	value: T,
+	--- Returns `value`.
+	unwrap: (self: any) -> T,
+}
+
+export type Err = {
+	success: false,
+	error: Error,
+	--- Throws `error` (the table itself; `tostring` gives its message).
+	--- Typed `any`: Luau cannot call a union of two function types, and this
+	--- keeps `result:unwrap()` callable on `Result<T>` while `success` still
+	--- narrows the union.
+	unwrap: any,
+}
+
+--- What every fallible library call returns. See `result.luau`.
+export type Result<T> = Ok<T> | Err
+
 --- FIFO mutex for coroutines. See `mutex.luau`.
 export type Mutex = {
 	_locked: boolean,
-	_closed: string?,
+	--- The `Error` (a `profile_closed`) every lock is rejected with once closed.
+	_closed: any?,
 	_waiters: { thread },
 	_settlers: { thread },
 
@@ -151,7 +353,7 @@ export type Mutex = {
 	wait_settled: (self: Mutex) -> (),
 	lock: (self: Mutex) -> (),
 	unlock: (self: Mutex) -> (),
-	close: (self: Mutex, reason: string) -> (),
+	close: (self: Mutex, reason: any) -> (),
 	is_locked: (self: Mutex) -> boolean,
 	is_closed: (self: Mutex) -> boolean,
 	with: (self: Mutex, fn: () -> ...any) -> any,
@@ -170,9 +372,9 @@ export type TxPatch = {
 	--- Set once `prepare` succeeded (the record carries `pending`).
 	prepared: boolean,
 
-	--- Phase 1: persist `pending` next to the current data. Returns false when
-	--- the profile no longer owns its lock. May throw.
-	prepare: (pending: Pending) -> boolean,
+	--- Phase 1: persist `pending` next to the current data. Throws an `Error`
+	--- (`lock_lost`, `tx_lock_lost`, `lockless_locked`, `roblox`, ...) on failure.
+	prepare: (pending: Pending) -> (),
 	--- Applies the outcome in memory. Called exactly once by the operation.
 	commit: (operation: TxOperation) -> (),
 	abort: (operation: TxOperation) -> (),
@@ -227,11 +429,14 @@ export type ProfileBase<T = any> = {
 	--- Operations waiting for this profile to write a record without `pending`.
 	_cleanup_txs: Array<TxOperation>,
 
-	--- Current data. Throws if the profile is closed or (lockless) not fetched.
+	--- Current data. Throws an `Error` (`profile_closed`, or `not_fetched` for
+	--- a lockless profile) instead of returning a Result: it is a plain accessor.
 	get_data: (self: ProfileBase<T>) -> T,
-	save: (self: ProfileBase<T>) -> (),
+	save: (self: ProfileBase<T>) -> Result<nil>,
 	unload: (self: ProfileBase<T>) -> (),
-	update: (self: ProfileBase<T>, (T) -> T | false) -> boolean,
+	--- Ok(true) when the data changed, Ok(false) when the dispatcher returned
+	--- nil / false. An error thrown by the dispatcher propagates as is.
+	update: (self: ProfileBase<T>, dispatcher: DataDispatcher<T>) -> Result<boolean>,
 
 	on_change: (self: ProfileBase<T>, callback: (new: T, old: T?) -> ()) -> (),
 	on_save: (self: ProfileBase<T>, callback: () -> ()) -> (),
@@ -256,6 +461,9 @@ export type ProfileBase<T = any> = {
 export type Profile<T = any> = ProfileBase<T> & {
 	kind: "locked",
 	last_write: number,
+	--- The id of this acquisition's lock; re-stamped unchanged on every save,
+	--- replaced by `readquire`. See `Lock.id`.
+	lock_id: string,
 	--- 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.
@@ -274,13 +482,21 @@ export type Profile<T = any> = ProfileBase<T> & {
 
 	--- 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.
-	release: (self: Profile<T>) -> (),
+	release: (self: Profile<T>) -> Result<nil>,
 	--- Takes the session lock again (waits like `load` does) and adopts the
 	--- stored record as the current data. No-op when already locked.
-	readquire: (self: Profile<T>) -> (),
-
-	-- internal, used by transactions. Returns false when the lock is gone.
-	_write_record: (self: Profile<T>, options: ProfileWriteOptions) -> boolean,
+	readquire: (self: Profile<T>) -> Result<nil>,
+
+	-- internal, used by transactions. Returns false (and the lock now on the
+	-- record) when the lock is gone.
+	_write_record: (self: Profile<T>, options: ProfileWriteOptions) -> (boolean, Lock?),
+
+	--- internal, set by the store: called once, as soon as the profile stops
+	--- being usable (an unload before its final write, or a lost lock), so the
+	--- key can be loaded again without waiting for that write.
+	_on_detach: (() -> ())?,
+	--- internal: whether `_on_detach` has run.
+	_detached: boolean,
 }
 
 export type ProfileWriteOptions = {
@@ -312,7 +528,7 @@ export type LocklessProfile<T = any> = ProfileBase<T> & {
 		lock_lost: Array<() -> ()>,
 	},
 
-	fetch: (self: LocklessProfile<T>) -> T,
+	fetch: (self: LocklessProfile<T>) -> Result<T>,
 
 	-- internal, used by transactions
 	_write_queued: (self: LocklessProfile<T>, options: LocklessWriteOptions) -> (),
@@ -328,6 +544,7 @@ export type PeekProfile<T = any> = {
 	_datastore: DatastoreHandle,
 
 	--- Lock currently on the record (session or transaction), nil when free.
+	--- Its `id` names an acquisition, not a server (see `Lock.id`).
 	lock: Lock?,
 	--- Transaction marker on the record, if any. Left as stored, never resolved.
 	pending: Pending<T>?,
@@ -340,7 +557,7 @@ export type PeekProfile<T = any> = {
 	get_data: (self: PeekProfile<T>) -> T,
 	--- Calls `GetAsync` again and replaces `lock`, `pending`, `migrations` and
 	--- the data. Yields.
-	refresh: (self: PeekProfile<T>) -> T,
+	refresh: (self: PeekProfile<T>) -> Result<T>,
 }
 
 export type LocklessWriteOptions = {
@@ -367,7 +584,9 @@ export type LoadOptions = {
 export type MigrationsResult = {
 	applied: boolean,
 	success: boolean,
-	err: any,
+	--- `outdated` when the record lists more migrations than declared,
+	--- `migration_mismatch` when a name differs
+	err: (MigrationMismatchError | OutdatedError)?,
 	result: any,
 	new_migrations: { string },
 }

package/src/utils.luau

@@ -1,3 +1,4 @@
+local errors = require "./errors"
 local types = require "./types"
 
 export type Counter = types.Counter
@@ -74,7 +75,9 @@ function utils.uuid(): string
 	return table.concat(chars)
 end
 
-function utils.retry<T>(config: types.RetryConfig, callback: () -> T): T
+--- Calls `callback` up to `retry_attempts` times with exponential backoff.
+--- Returns the result, or false and the last error once every attempt failed.
+local function retry<T>(config: types.RetryConfig, callback: () -> T): (boolean, T | any)
 	local last_error: any = nil
 	local attempts = config.retry_attempts
 	local base = config.retry_base
@@ -82,14 +85,45 @@ function utils.retry<T>(config: types.RetryConfig, callback: () -> T): T
 	for attempt = 1, attempts do
 		local ok, result = pcall(callback)
 		if ok then
-			return result
+			return true, result
 		end
 		last_error = result
 		if attempt < attempts then
 			config._scheduler.wait(base * 2 ^ (attempt - 1))
 		end
 	end
-	error(last_error, 0)
+	return false, last_error
+end
+
+--- `datastore.get_async(key)` under the retry policy. Throws a `roblox`
+--- error once every attempt failed.
+function utils.get_async(config: types.RetryConfig, datastore: types.DatastoreHandle, key: string): any?
+	local ok, result = retry(config, function()
+		return datastore.get_async(key)
+	end)
+	if not ok then
+		error(errors.roblox("get_async", datastore.name, key, result), 0)
+	end
+	return result
+end
+
+--- `datastore.update_async(key, transform, user_ids)` under the retry policy.
+--- Throws a `roblox` error once every attempt failed. `transform` must not
+--- throw: whatever it throws counts as a storage failure and is retried.
+function utils.update_async(
+	config: types.RetryConfig,
+	datastore: types.DatastoreHandle,
+	key: string,
+	transform: (old: any?) -> any?,
+	user_ids: { number }?
+): any?
+	local ok, result = retry(config, function()
+		return datastore.update_async(key, transform, user_ids)
+	end)
+	if not ok then
+		error(errors.roblox("update_async", datastore.name, key, result), 0)
+	end
+	return result
 end
 
 function utils.counter(): Counter