@rbxts/dataforge 0.1.0

package/src/hooks/roblox.luau

@@ -0,0 +1,68 @@
+--!nocheck
+--!nolint UnknownGlobal
+
+local types = require "../types"
+
+--[[
+	DataStoreService hook. Only usable inside Roblox.
+]]
+
+local roblox_hook = {}
+
+function roblox_hook.create(): types.Hook
+	local DataStoreService = game:GetService "DataStoreService"
+	local handles: { [string]: types.DatastoreHandle } = {}
+
+	local self = {} :: types.Hook
+
+	self.warn = warn
+
+	function self.job_id()
+		return game.JobId :: string
+	end
+
+	function self.get_datastore(name: string): types.DatastoreHandle
+		local existing = handles[name]
+		if existing then
+			return existing
+		end
+		local datastore = DataStoreService:GetDataStore(name)
+		local handle = {} :: types.DatastoreHandle
+		handle.name = name
+
+		function handle.get_async(key: string): any?
+			return (datastore:GetAsync(key))
+		end
+
+		function handle.set_async(key: string, value: any, user_ids: { number }?)
+			datastore:SetAsync(key, value, user_ids)
+		end
+
+		function handle.update_async(key: string, transform: (old: any?) -> any?, user_ids: { number }?): any?
+			-- Capture the result inside the callback so semantics do not depend on
+			-- what UpdateAsync returns when the callback cancels.
+			local result: any = nil
+			datastore:UpdateAsync(key, function(old: any?)
+				local new = transform(old)
+				if new == nil then
+					result = old
+					return nil
+				end
+				result = new
+				return new, user_ids
+			end)
+			return result
+		end
+
+		function handle.remove_async(key: string)
+			datastore:RemoveAsync(key)
+		end
+
+		handles[name] = handle
+		return handle
+	end
+
+	return self
+end
+
+return roblox_hook

package/src/init.luau

@@ -0,0 +1,58 @@
+local store = require "@self/store"
+local tx = require "@self/tx/handle"
+local types = require "@self/types"
+
+local memory_hook = require "@self/hooks/memory"
+local roblox_hook = require "@self/hooks/roblox"
+
+local virtual_scheduler = require "@self/schedulers/virtual"
+local roblox_scheduler = require "@self/schedulers/roblox"
+
+type Array<T> = { T }
+
+export type Store<T = any> = store.Store<T>
+export type Config<T = any> = types.Config<T>
+export type TransactionConfig = types.TransactionConfig
+export type TxContext = types.TxContext
+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>
+
+local dataforge = {}
+
+function dataforge.create_store<T>(config: Config<T>): Store<T>
+	return store.create(config)
+end
+
+--- Atomically updates any set of profiles, across stores and mixing locked and
+--- lockless ones.
+function dataforge.transaction(
+	profiles: Array<ProfileBase>,
+	process: (ctx: TxContext) -> boolean?,
+	config: TransactionConfig?
+): boolean
+	local first = profiles[1]
+	local defaults: TransactionConfig? = if first
+		then {
+			_hook = first.config._hook,
+			_scheduler = first.config._scheduler,
+			retry_attempts = first.config.retry_attempts,
+			retry_base = first.config.retry_base,
+		}
+		else nil
+
+	return tx.run(tx.resolve_config(config, defaults), profiles, process)
+end
+
+dataforge.hooks = {
+	memory = memory_hook,
+	roblox = roblox_hook,
+}
+
+dataforge.schedulers = {
+	virtual = virtual_scheduler,
+	roblox = roblox_scheduler,
+}
+
+return dataforge

package/src/mutex.luau

@@ -0,0 +1,107 @@
+--!strict
+
+local types = require "./types"
+
+--[[
+	FIFO mutex for coroutines.
+]]
+
+export type Mutex = types.Mutex
+
+local mutex = {}
+mutex.__index = mutex
+
+function mutex.create(scheduler: types.Scheduler): Mutex
+	local self = {} :: Mutex
+	self._locked = false
+	self._closed = nil
+	self._waiters = {}
+	self._settlers = {}
+	self.scheduler = scheduler
+
+	return setmetatable(self, mutex) :: any
+end
+
+function mutex.lock(self: Mutex)
+	if self._closed then
+		error(self._closed, 2)
+	end
+	if not self._locked then
+		self._locked = true
+		return
+	end
+	table.insert(self._waiters, coroutine.running())
+	-- resumed with a reason only when the mutex was closed while waiting
+	local rejection = coroutine.yield()
+	if rejection ~= nil then
+		error(rejection, 2)
+	end
+end
+
+local function resume_settlers(self: Mutex)
+	local settlers = self._settlers
+	self._settlers = {}
+	for _, thread in settlers do
+		self.scheduler.spawn(thread)
+	end
+end
+
+function mutex.unlock(self: Mutex)
+	if not self._locked then
+		error "mutex: unlock called while not locked"
+	end
+	local next_waiter = table.remove(self._waiters, 1)
+	if next_waiter == nil then
+		self._locked = false
+		resume_settlers(self)
+		return
+	end
+	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)
+	if self._closed then
+		return
+	end
+	self._closed = reason
+
+	local waiters = self._waiters
+	self._waiters = {}
+	for _, thread in waiters do
+		self.scheduler.spawn(thread, reason)
+	end
+end
+
+function mutex.is_locked(self: Mutex): boolean
+	return self._locked
+end
+
+function mutex.is_closed(self: Mutex): boolean
+	return self._closed ~= nil
+end
+
+function mutex.with(self: Mutex, fn: () -> ...any): any
+	self:lock()
+	local ok, result = pcall(fn)
+	self:unlock()
+	if not ok then
+		error(result, 0)
+	end
+	return result
+end
+
+--- Yields until the mutex is unlocked with no one waiting. Works after `close`.
+function mutex.wait_settled(self: Mutex)
+	if not self._locked then
+		return
+	end
+
+	table.insert(self._settlers, coroutine.running())
+	coroutine.yield()
+end
+
+return {
+	create = mutex.create,
+}

package/src/profile/common.luau

@@ -0,0 +1,102 @@
+local types = require "../types"
+
+type Array<T> = { T }
+
+export type ProfileBase<T = any> = types.ProfileBase<T>
+export type LoadOptions = types.LoadOptions
+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.
+function common.assert_open(self: ProfileBase)
+	if not self.open then
+		error(`datastore: profile "{self.key}" is closed`, 3)
+	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
+	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`,
+			new_migrations = applied,
+		}
+	end
+
+	for index = 1, applied_count do
+		local expected = migrations[index].name
+		local actual = applied[index]
+		if actual ~= expected then
+			return {
+				applied = false,
+				success = false,
+				err = `migration mismatch at index {index}: record has "{actual}", declared is "{expected}"`,
+				new_migrations = applied,
+			}
+		end
+	end
+
+	if applied_count == #migrations then
+		return { applied = false, success = true, result = data, new_migrations = applied }
+	end
+
+	local new_migrations = table.clone(applied)
+	for index = applied_count + 1, #migrations do
+		local migration = migrations[index]
+		data = migration.apply(data)
+		table.insert(new_migrations, migration.name)
+	end
+
+	return { applied = true, success = true, result = data, new_migrations = new_migrations }
+end
+
+--- Names of every declared migration; what a fresh template counts as having applied.
+function common.all_migration_names(migrations: Array<types.Migration>): { string }
+	local names = table.create(#migrations) :: { string }
+	for index, migration in migrations do
+		names[index] = migration.name
+	end
+	return names
+end
+
+function common.is_lock_owned(record: types.DataRecord?, job_id: string)
+	if not record then
+		return false
+	end
+
+	local lock = record.lock
+	if not lock then
+		return false
+	end
+
+	return lock.id == job_id
+end
+
+function common.is_locked_for(record: types.DataRecord?, job_id: string, now: number)
+	if not record then
+		return false
+	end
+	local lock = record.lock
+	if not lock then
+		return false
+	end
+
+	return lock.id ~= job_id and lock.expires > now
+end
+
+function common.has_lock(record: types.DataRecord?)
+	if not record then
+		return false
+	end
+	return not not record.lock
+end
+
+return common