@trioforge/crucible 0.0.0-stage → 0.2.0

package/out/internal/reactive/ownership.luau

@@ -0,0 +1,626 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local runtimeDiagnostic = TS.import(script, script.Parent.Parent, "diagnostics").runtimeDiagnostic
+local _lifecycle = TS.import(script, script.Parent.Parent, "lifecycle")
+local closeScope = _lifecycle.closeScope
+local current = _lifecycle.current
+local drain = _lifecycle.drain
+local enabling = _lifecycle.enabling
+local hasEnded = _lifecycle.hasEnded
+local openScope = _lifecycle.openScope
+local call = TS.import(script, script.Parent.Parent, "runner").call
+local _context = TS.import(script, script.Parent, "context")
+local boundary = _context.boundary
+local discard = _context.discard
+local pop = _context.pop
+local push = _context.push
+local top = _context.top
+local _graph = TS.import(script, script.Parent, "graph")
+local finishOpen = _graph.finishOpen
+local guardPure = _graph.guardPure
+local originOf = _graph.originOf
+local releaseEdges = _graph.releaseEdges
+local OWNER_CHILDREN_WARNING = TS.import(script, script.Parent, "limits").OWNER_CHILDREN_WARNING
+--* @internal 
+--[[
+	*
+	 * @internal
+	 * How a lifetime releases one owned value. `own` decides it once, when the value is owned. The engine's kinds come
+	 * last, so `kind >= Release.Disconnect` is a release that runs no Luau.
+	 
+]]
+--* @internal Everything that must end, ends exactly once, through one of these. 
+--* @internal 
+--* @internal 
+local NO_OWNER = "effect() needs an owner: create it in a Subsystem or behaviour, or inside scope()"
+local generations = setmetatable({}, {
+	__mode = "k",
+})
+local intervals = setmetatable({}, {
+	__mode = "k",
+})
+--* Bodies running now, outermost first. Boundaries nest synchronously, so one stack serves every thread. 
+local bodies = {}
+local describe = tostring
+--* @internal 
+local function useDescribe(port)
+	describe = port
+end
+--* @internal "JobService" or "DoorPrompt on Workspace.Door", for diagnostics. 
+local function ownerLabel(owner)
+	if owner == nil then
+		return "a root scope"
+	end
+	local id = (owner.record).id
+	return if owner.instance == nil then id else `{id} on {describe(owner.instance)}`
+end
+--* @internal 
+local function newLifetime(role, parent, owner, effect)
+	local lifetime = {
+		kind = 3,
+		role = role,
+		parent = parent,
+		owner = owner,
+		effect = effect,
+		count = 0,
+		releases = {},
+		ended = false,
+		finished = false,
+		linked = false,
+		warned = false,
+	}
+	return lifetime
+end
+--* @internal Appends `child` to `parent`'s children, newest last. 
+local function adopt(parent, child)
+	child.prev = parent.tail
+	child.next = nil
+	if parent.tail == nil then
+		parent.head = child
+	else
+		parent.tail.next = child
+	end
+	parent.tail = child
+	child.linked = true
+	parent.count += 1
+	if parent.role == 0 and parent.count >= OWNER_CHILDREN_WARNING and not parent.warned then
+		parent.warned = true
+		runtimeDiagnostic("warning", `Crucible: {ownerLabel(parent.owner)} owns {OWNER_CHILDREN_WARNING} live effects and scopes; one may be created every frame`)
+	end
+end
+local function leave(child)
+	local parent = child.parent
+	if not child.linked or parent == nil then
+		return nil
+	end
+	child.linked = false
+	if child.prev == nil then
+		parent.head = child.next
+	else
+		child.prev.next = child.next
+	end
+	if child.next == nil then
+		parent.tail = child.prev
+	else
+		child.next.prev = child.prev
+	end
+	child.prev = nil
+	child.next = nil
+	parent.count -= 1
+end
+local endLifetime
+local function generation(s)
+	local _s = s
+	local lifetime = generations[_s]
+	if lifetime == nil then
+		local created = newLifetime(0, nil, s)
+		lifetime = created
+		local _s_1 = s
+		generations[_s_1] = created
+		if s.subscriptions == nil then
+			s.subscriptions = {}
+		end
+		local _exp = s.subscriptions
+		table.insert(_exp, function()
+			local _s_2 = s
+			generations[_s_2] = nil
+			endLifetime(created)
+		end)
+	end
+	return lifetime
+end
+local function interval(s)
+	local _s = s
+	local lifetime = intervals[_s]
+	if lifetime == nil then
+		local parent = generation(s)
+		lifetime = newLifetime(1, parent, s)
+		adopt(parent, lifetime)
+		local _s_1 = s
+		local _lifetime = lifetime
+		intervals[_s_1] = _lifetime
+	end
+	return lifetime
+end
+--[[
+	*
+	 * @internal
+	 * The owner of something created now: the innermost frame's lifetime; else the running Crucible object's enable
+	 * interval while its Enable step runs, or its generation; else none. A returned lifetime may have ended.
+	 
+]]
+local ownerAt
+local function resolveOwner()
+	return ownerAt(top())
+end
+function ownerAt(frame)
+	local _result = frame
+	if _result ~= nil then
+		_result = _result.lifetime
+	end
+	if _result ~= nil then
+		return frame.lifetime
+	end
+	local s = current()
+	if s == nil then
+		return nil
+	end
+	if hasEnded(s) then
+		local ended = newLifetime(0, nil, s)
+		ended.ended = true
+		ended.finished = true
+		return ended
+	end
+	return if enabling() == s then interval(s) else generation(s)
+end
+--* @internal Core edit E1: lifecycle calls it after `onDisable` and when it releases a generation. Idempotent. 
+local function endInterval(s)
+	local _s = s
+	local lifetime = intervals[_s]
+	if lifetime == nil then
+		return nil
+	end
+	local _s_1 = s
+	intervals[_s_1] = nil
+	endLifetime(lifetime)
+end
+--* @internal Detaches an effect from the graph for good. No diagnostic: an ending is not a failure. 
+local function halt(effect)
+	if effect.stopped then
+		return nil
+	end
+	effect.stopped = true
+	releaseEdges(effect)
+end
+local function latch(root)
+	if root.head == nil then
+		root.ended = true
+		return nil
+	end
+	local pending = { root }
+	while #pending > 0 do
+		-- ▼ Array.pop ▼
+		local _length = #pending
+		local _result = pending[_length]
+		pending[_length] = nil
+		-- ▲ Array.pop ▲
+		local lifetime = _result
+		lifetime.ended = true
+		local child = lifetime.head
+		while child ~= nil do
+			if child.kind == 2 then
+				halt(child)
+				if child.run ~= nil and not child.run.ended then
+					local _run = child.run
+					table.insert(pending, _run)
+				end
+			elseif not child.ended then
+				local _child = child
+				table.insert(pending, _child)
+			end
+			child = child.next
+		end
+	end
+end
+local function under(body, lifetime)
+	local at = body
+	while at ~= nil do
+		if at == lifetime then
+			return true
+		end
+		at = at.parent
+	end
+	return false
+end
+--[[
+	*
+	 * @internal
+	 * Ends a lifetime once: latch it and everything under it, then, unless a body under it is still running, end its
+	 * children newest first, run its releases newest first, and unlink it. A running body defers those steps to its
+	 * completion.
+	 
+]]
+local finish
+function endLifetime(lifetime)
+	if lifetime.ended then
+		return nil
+	end
+	latch(lifetime)
+	for _, body in bodies do
+		if not under(body, lifetime) then
+			continue
+		end
+		if body.deferred == nil then
+			body.deferred = {}
+		end
+		local _deferred = body.deferred
+		local _lifetime = lifetime
+		table.insert(_deferred, _lifetime)
+		return nil
+	end
+	finish(lifetime)
+end
+local retire, runReleases
+function finish(lifetime)
+	if lifetime.finished then
+		return nil
+	end
+	lifetime.finished = true
+	local child = lifetime.tail
+	while child ~= nil do
+		local previous = child.prev
+		if child.kind == 2 then
+			retire(child)
+		else
+			finish(child)
+		end
+		child = previous
+	end
+	local releases = lifetime.releases
+	runReleases(lifetime, releases, #releases - 2)
+	table.clear(releases)
+	leave(lifetime)
+end
+--* @internal Stops an effect for good: detached, its current run ended, unlinked from its owner. 
+function retire(effect)
+	halt(effect)
+	local run = effect.run
+	effect.run = nil
+	if run ~= nil then
+		latch(run)
+		finish(run)
+	end
+	leave(effect)
+end
+local function releaseLabel(kind, value)
+	if kind == 3 then
+		return "of a connection"
+	end
+	if kind == 4 then
+		return `of {describe(value)}`
+	end
+	if kind == 5 then
+		return "of a thread"
+	end
+	local code = if kind == 0 then value elseif kind == 1 then value.destroy else value.Destroy
+	return if type(code) == "function" then `at {originOf(code)}` else `of {tostring(value)}`
+end
+local function reportRelease(lifetime, kind, value, err)
+	runtimeDiagnostic("error", `Crucible: cleanup {releaseLabel(kind, value)} ({ownerLabel(lifetime.owner)}) failed: {tostring(err)}`)
+end
+local function disconnect(connection)
+	connection:Disconnect()
+end
+local function destroyInstance(instance)
+	instance:Destroy()
+end
+--[[
+	*
+	 * `Disconnect`, `Destroy` and `task.cancel` run no Luau on this thread and cannot yield, so a `pcall` is their
+	 * boundary. A throw is reported and nobody is faulted.
+	 
+]]
+local function releaseEngine(lifetime, kind, value)
+	local engine
+	if kind == 3 then
+		engine = disconnect
+	elseif kind == 4 then
+		engine = destroyInstance
+	else
+		engine = task.cancel
+	end
+	local ok, err = pcall(engine, value)
+	if not ok then
+		pcall(reportRelease, lifetime, kind, value, err)
+	end
+end
+--* A lifetime's releases that run code, newest first, on one worker until one fails or yields. Its own frame. 
+--[[
+	*
+	 * Runs `batch` from `batch.at` down on the running worker, as its ended lifetime. A release that runs code opens its
+	 * own lifecycle scope, as `within` would. One that leaves requests for a drain outside any other scope stops the
+	 * batch with `true`, so the caller drains before the next release, as that release's own `within` would have.
+	 
+]]
+local function releaseBatch(batch)
+	batch.worker = coroutine.running()
+	local lifetime = batch.lifetime
+	local releases = batch.releases
+	push(batch)
+	do
+		local i = batch.at
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i -= 2
+			else
+				_shouldIncrement = true
+			end
+			if not (i >= 0) then
+				break
+			end
+			batch.at = i
+			local kind = releases[i + 1]
+			local value = releases[i + 2]
+			if kind >= 3 then
+				releaseEngine(lifetime, kind, value)
+				continue
+			end
+			batch.scoped = true
+			openScope()
+			if kind == 0 then
+				value()
+			elseif kind == 1 then
+				value:destroy()
+			else
+				value:Destroy()
+			end
+			batch.scoped = false
+			if closeScope() then
+				pop(batch)
+				return true
+			end
+		end
+	end
+	pop(batch)
+	return false
+end
+--* The release at `batch.at` threw or yielded, and its worker is gone: finish what it left open and report it. 
+local function failRelease(batch, result, value)
+	finishOpen({
+		frame = nil,
+		result = result,
+		value = value,
+		open = discard(batch.worker, false),
+		after = nil,
+	})
+	local at = batch.at
+	reportRelease(batch.lifetime, batch.releases[at + 1], batch.releases[at + 2], value)
+	if not batch.scoped then
+		return nil
+	end
+	batch.scoped = false
+	if closeScope() then
+		drain()
+	end
+end
+--[[
+	*
+	 * Releases `releases` from index `from` down, as their ended lifetime. Engine values before the first function or
+	 * `destroy()` release here. From there one worker runs the rest as a batch. A release that throws or yields loses
+	 * that worker: it is cancelled and reported, and the batch goes on from the next release on a fresh one. Each
+	 * release's requests still apply when it returns, before the next one runs.
+	 
+]]
+function runReleases(lifetime, releases, from)
+	local batch
+	local i = from
+	while i >= 0 do
+		local kind = releases[i + 1]
+		if kind >= 3 then
+			releaseEngine(lifetime, kind, releases[i + 2])
+			i -= 2
+			continue
+		end
+		if batch == nil then
+			batch = {
+				kind = 3,
+				lifetime = lifetime,
+				releases = releases,
+				at = i,
+				scoped = false,
+			}
+		else
+			batch.at = i
+		end
+		local result, value = call(releaseBatch, batch, nil, lifetime.owner)
+		if result ~= 0 then
+			failRelease(batch, result, value)
+		elseif value == true then
+			drain()
+		end
+		i = batch.at - 2
+	end
+end
+--* Releases one value now, as its ended lifetime: a throw or a yield is reported and nobody is faulted. 
+local function releaseValue(lifetime, kind, value)
+	if kind >= 3 then
+		releaseEngine(lifetime, kind, value)
+	else
+		runReleases(lifetime, { kind, value }, 0)
+	end
+end
+--* @internal 
+local function hold(lifetime, kind, value)
+	local releases = lifetime.releases
+	local size = #releases
+	releases[size + 1] = kind
+	releases[size + 2] = value
+end
+--[[
+	*
+	 * @internal
+	 * Runs a lifetime's own body in a boundary, under `frame`, whose lifetime it is. While it runs, endings that reach
+	 * it wait; at completion `after` runs, then those endings.
+	 
+]]
+local completeBody
+local function runBody(frame, body, arg, after)
+	local lifetime = frame.lifetime
+	table.insert(bodies, lifetime)
+	boundary(lifetime.owner, frame, body, arg, completeBody, after)
+end
+local function settleBody(completion)
+	finishOpen(completion)
+	completion.after(completion)
+end
+function completeBody(completion)
+	local lifetime = completion.frame.lifetime
+	local index = (table.find(bodies, lifetime) or 0) - 1
+	if index >= 0 then
+		table.remove(bodies, index + 1)
+	end
+	local ok, err = pcall(settleBody, completion)
+	local deferred = lifetime.deferred
+	lifetime.deferred = nil
+	if deferred ~= nil then
+		for _, ending in deferred do
+			finish(ending)
+		end
+	end
+	if not ok then
+		error(err, 0)
+	end
+end
+--* @internal 
+local startScope
+local function createScope(setup)
+	guardPure("create scopes")
+	local parent = resolveOwner()
+	local _result = parent
+	if _result ~= nil then
+		_result = _result.ended
+	end
+	if _result then
+		return function() end
+	end
+	return startScope(parent, setup)
+end
+--* @internal A scope that only its dispose ends, whatever owner is current. 
+local function createRootScope(setup)
+	guardPure("create scopes")
+	return startScope(nil, setup)
+end
+function startScope(parent, setup)
+	local _exp = parent
+	local _result = parent
+	if _result ~= nil then
+		_result = _result.owner
+	end
+	local scope = newLifetime(3, _exp, _result)
+	if parent ~= nil then
+		adopt(parent, scope)
+	end
+	local failed = false
+	local failure
+	runBody({
+		kind = 3,
+		lifetime = scope,
+	}, setup, nil, function(completion)
+		if completion.result == 0 then
+			return nil
+		end
+		failed = true
+		failure = completion.value
+		endLifetime(scope)
+	end)
+	if failed then
+		error(failure, 0)
+	end
+	return function()
+		return endLifetime(scope)
+	end
+end
+--* `guardPure("register cleanups")` that returns the frame it read, so `register` does not read it again. 
+local function cleanupFrame()
+	local frame = top()
+	local _pure = frame
+	if _pure ~= nil then
+		_pure = _pure.pure
+	end
+	local pure = _pure
+	if pure ~= nil then
+		error(`{pure} must not register cleanups`, 0)
+	end
+	return frame
+end
+local function register(frame, kind, value)
+	local owner = ownerAt(frame)
+	if owner == nil then
+		error(NO_OWNER, 0)
+	end
+	if owner.ended then
+		releaseValue(owner, kind, value)
+	else
+		hold(owner, kind, value)
+	end
+end
+--* @internal 
+local function registerCleanup(release)
+	local frame = cleanupFrame()
+	-- A nil from untyped Luau would shift every pair after it, so it is dropped.
+	if release == nil then
+		return nil
+	end
+	register(frame, 0, release)
+end
+local NOT_OWNABLE = "own() takes a function, an RBXScriptConnection, an Instance, a thread, or an object with destroy() or Destroy()"
+local function classify(value)
+	local _value = value
+	local typeName = typeof(_value)
+	if typeName == "RBXScriptConnection" then
+		return 3
+	end
+	if typeName == "Instance" then
+		return 4
+	end
+	if typeName == "function" then
+		return 0
+	end
+	if typeName == "thread" then
+		return 5
+	end
+	if typeName == "table" then
+		local _destroy = value.destroy
+		if type(_destroy) == "function" then
+			return 1
+		end
+		local _destroy_1 = value.Destroy
+		if type(_destroy_1) == "function" then
+			return 2
+		end
+	end
+	error(`{NOT_OWNABLE}; got a {typeName}`, 0)
+end
+--* @internal 
+local function registerOwned(value)
+	local frame = cleanupFrame()
+	register(frame, classify(value), value)
+end
+return {
+	useDescribe = useDescribe,
+	ownerLabel = ownerLabel,
+	newLifetime = newLifetime,
+	adopt = adopt,
+	resolveOwner = resolveOwner,
+	endInterval = endInterval,
+	endLifetime = endLifetime,
+	retire = retire,
+	hold = hold,
+	runBody = runBody,
+	createScope = createScope,
+	createRootScope = createRootScope,
+	registerCleanup = registerCleanup,
+	registerOwned = registerOwned,
+	NO_OWNER = NO_OWNER,
+}

package/out/internal/registry.d.ts

@@ -0,0 +1 @@
+export {};