@rbxts/planck 0.3.0-alpha.2 → 0.3.0-rc.1

package/src/init.luau

@@ -1,207 +1,36 @@
-local Phase = require(script.Phase) :: any
-local Pipeline = require(script.Pipeline) :: any
-local Scheduler = require(script.Scheduler) :: any
-
-local conditions = require(script.conditions)
-local utils = require(script.utils)
-
-type GenericTable = utils.GenericTable
-type SignalLike<U...> = utils.SignalLike<U...>
-type ConnectionLike = utils.ConnectionLike
-type ConnectFn<T, U...> = utils.ConnectFn<T, U...>
-type Callback<U...> = utils.Callback<U...>
-
-export type CleanupFn<U...> = (U...) -> ()
-
-export type SystemFn<U...> = (U...) -> ()
-
-export type InitializerResult<U...> = {
-	system: SystemFn<U...>?,
-	cleanup: CleanupFn<U...>?,
-}
-
-export type InitializerSystemFn<U...> =
-	| ((U...) -> SystemFn<U...>)
-	| ((U...) -> (SystemFn<U...>, CleanupFn<U...>))
-	| ((U...) -> InitializerResult<U...>)
-
-export type SystemTable<U...> = {
-	system: SystemFn<U...> | InitializerSystemFn<U...>,
-	phase: Phase?,
-	name: string?,
-	runConditions: { (U...) -> boolean }?,
-	[any]: any,
-}
-
-export type System<U...> =
-	SystemFn<U...>
-	| InitializerSystemFn<U...>
-	| SystemTable<U...>
-
-export type Phase = {
-	PreStartup: Phase,
-	Startup: Phase,
-	PostStartup: Phase,
-
-	new: (debugName: string?) -> Phase,
-}
-
-export type Pipeline = {
-	Startup: Pipeline,
-
-	insert: (self: Pipeline, phase: Phase) -> Pipeline,
-	insertAfter: (self: Pipeline, phase: Phase, after: Phase) -> Pipeline,
-	insertBefore: (self: Pipeline, phase: Phase, before: Phase) -> Pipeline,
-	new: (debugName: string?) -> Pipeline,
-}
-
-type Plugin<U...> =
-	{
-		build: (self: Plugin<U...>, scheduler: Scheduler<U...>) -> (),
-		[any]: any,
-	}
-	| {
-		build: (self: Plugin<U...>, scheduler: Scheduler<U...>) -> (),
-		cleanup: (self: Plugin<U...>) -> (),
-		[any]: any,
-	}
-
-export type Scheduler<U...> = {
-	addPlugin: (self: Scheduler<U...>, plugin: Plugin<U...>) -> Scheduler<U...>,
-
-	addSystem: (
-		self: Scheduler<U...>,
-		system: System<U...>,
-		phase: Phase?
-	) -> Scheduler<U...>,
-
-	addSystems: (
-		self: Scheduler<U...>,
-		systems: { System<U...> },
-		phase: Phase?
-	) -> Scheduler<U...>,
-
-	editSystem: (
-		self: Scheduler<U...>,
-		system: System<U...>,
-		new: Phase
-	) -> Scheduler<U...>,
-
-	replaceSystem: (
-		self: Scheduler<U...>,
-		system: System<U...>,
-		new: System<U...>
-	) -> Scheduler<U...>,
-
-	removeSystem: (
-		self: Scheduler<U...>,
-		system: System<U...>
-	) -> Scheduler<U...>,
-
-	addRunCondition: ((
-		self: Scheduler<U...>,
-		system: System<U...>,
-		fn: (U...) -> boolean,
-		...any
-	) -> Scheduler<U...>) & ((
-		self: Scheduler<U...>,
-		phase: Phase,
-		fn: (U...) -> boolean,
-		...any
-	) -> Scheduler<U...>) & ((
-		self: Scheduler<U...>,
-		pipeline: Pipeline,
-		fn: (U...) -> boolean,
-		...any
-	) -> Scheduler<U...>),
-
-	run: ((self: Scheduler<U...>, system: System<U...>) -> Scheduler<U...>)
-		& ((self: Scheduler<U...>, phase: Phase) -> Scheduler<U...>)
-		& ((self: Scheduler<U...>, pipeline: Pipeline) -> Scheduler<U...>),
-
-	runAll: (self: Scheduler<U...>) -> Scheduler<U...>,
-
-	getDeltaTime: (self: Scheduler<U...>) -> number,
-
-	insert: ((
-		self: Scheduler<U...>,
-		dependency: Phase | Pipeline
-	) -> Scheduler<U...>)
-		-- RBXScriptSignal & nil
-		& ((
-			self: Scheduler<U...>,
-			dependency: Phase | Pipeline,
-			signal: RBXScriptSignal<U...>
-		) -> Scheduler<U...>)
-		-- Instance & RBXScriptSignal
-		-- Instance & string
-		& ((
-			self: Scheduler<U...>,
-			dependency: Phase | Pipeline,
-			instance: Instance,
-			event: RBXScriptSignal<U...> | string
-		) -> Scheduler<U...>)
-		-- SignalLike & nil
-		& ((
-			self: Scheduler<U...>,
-			dependency: Phase | Pipeline,
-			signal: SignalLike<U...>
-		) -> Scheduler<U...>)
-		-- table & string
-		& ((
-			self: Scheduler<U...>,
-			dependency: Phase | Pipeline,
-			table: GenericTable,
-			event: string
-		) -> Scheduler<U...>)
-		-- table & connectable method
-		& (<T>(
-			self: Scheduler<U...>,
-			dependency: Phase | Pipeline,
-			instance: GenericTable,
-			connectMethod: (GenericTable, Callback<U...>, ...any) -> T
-		) -> Scheduler<U...>)
-		-- connectable function
-		& (<T>(
-			self: Scheduler<U...>,
-			dependency: Phase | Pipeline,
-			connectFn: (Callback<U...>, ...any) -> T
-		) -> Scheduler<U...>),
-
-	insertAfter: ((
-		self: Scheduler<U...>,
-		phase: Phase,
-		after: Phase | Pipeline
-	) -> Scheduler<U...>) & ((
-		self: Scheduler<U...>,
-		pipeline: Pipeline,
-		after: Phase | Pipeline
-	) -> Scheduler<U...>),
-
-	insertBefore: ((
-		self: Scheduler<U...>,
-		phase: Phase,
-		before: Phase | Pipeline
-	) -> Scheduler<U...>) & ((
-		self: Scheduler<U...>,
-		pipeline: Pipeline,
-		before: Phase | Pipeline
-	) -> Scheduler<U...>),
-
-	cleanup: (self: Scheduler<U...>) -> (),
-
-	new: (U...) -> Scheduler<U...>,
-}
-
-return {
-	Phase = Phase :: Phase,
-	Pipeline = Pipeline :: Pipeline,
-	Scheduler = Scheduler :: {
-		new: <U...>(U...) -> Scheduler<U...>,
-	},
-
-	isNot = conditions.isNot,
-	runOnce = conditions.runOnce,
-	timePassed = conditions.timePassed,
-	onEvent = conditions.onEvent,
-}
+local Phase = require(script.Phase)
+local Pipeline = require(script.Pipeline)
+local Scheduler = require(script.Scheduler)
+
+local conditions = require(script.conditions)
+
+export type Phase = Phase.Phase
+export type Pipeline = Pipeline.Pipeline
+export type Scheduler<U...> = Scheduler.Scheduler<U...>
+
+export type System<U...> = Scheduler.System<U...>
+export type SystemFn<U...> = Scheduler.SystemFn<U...>
+export type SystemTable<U...> = Scheduler.SystemTable<U...>
+export type InitializerSystemFn<U...> = Scheduler.InitializerSystemFn<U...>
+export type InitializerResult<U...> = Scheduler.InitializerResult<U...>
+export type CleanupFn<U...> = SystemFn<U...>
+
+export type SystemInfo<U...> = Scheduler.SystemInfo<U...>
+
+export type SystemHookContext = Scheduler.SystemHookContext
+export type SystemReplaceContext = Scheduler.SystemReplaceContext
+export type SystemEditedContext = Scheduler.SystemEditedContext
+export type SystemErrorContext = Scheduler.SystemErrorContext
+export type SystemCallContext = Scheduler.SystemCallContext
+export type PhaseContext = Scheduler.PhaseContext
+
+return {
+	Phase = Phase,
+	Pipeline = Pipeline,
+	Scheduler = Scheduler,
+
+	isNot = conditions.isNot,
+	runOnce = conditions.runOnce,
+	timePassed = conditions.timePassed,
+	onEvent = conditions.onEvent,
+}

package/src/utils.luau

@@ -1,18 +1,63 @@
-type Phase = any
-type Pipeline = any
+local Pipeline = require(script.Parent.Pipeline)
+local Phase = require(script.Parent.Phase)
 
-type SystemFn<U...> = (U...) -> ()
-type SystemInitializerFn<U...> = (U...) -> SystemFn<U...>
+type Pipeline = Pipeline.Pipeline
+type Phase = Phase.Phase
 
-type SystemTable<U...> = {
-	system: SystemFn<U...> | SystemInitializerFn<U...>,
+--- @type SystemFn ((U...) -> ())
+--- @within Scheduler
+--- Standard system function that runs every time it's scheduled
+export type SystemFn<U...> = (U...) -> ()
+type AnyFunction = (...any) -> ...any
+
+--- @type CleanupFn (() -> ())
+--- @within Scheduler
+--- Cleanup function called when system is removed
+
+export type InitializerResult<U...> =
+	{
+		system: SystemFn<U...>,
+	}
+	| {
+		cleanup: SystemFn<U...>,
+	}
+	| {
+		system: SystemFn<U...>,
+		cleanup: SystemFn<U...>,
+	}
+
+--- @type InitializerSystemFn ((U...) -> (SystemFn<U...> | (SystemFn<U...>, CleanupFn)))
+--- @within Scheduler
+--- Initializer system that returns the runtime function, optionally with cleanup
+export type InitializerSystemFn<U...> = (
+	U...
+) -> SystemFn<U...> | SystemFn<U...>
+
+export type InternalSystem<U...> = SystemFn<U...> | InitializerSystemFn<U...>
+
+--- @interface SystemTable
+--- @within Scheduler
+--- .system SystemFn<U...> | InitializerSystemFn<U...>
+--- .phase Phase?
+--- .name string?
+--- .runConditions {RunCondition}?
+--- .[any] any
+export type SystemTable<U...> = {
+	system: InternalSystem<U...>,
 	phase: Phase?,
+	name: string?,
+	runConditions: { (U...) -> boolean }?,
 	[any]: any,
 }
 
-type System<U...> = SystemFn<U...> | SystemInitializerFn<U...> | SystemTable<U...>
+--- @type System SystemFn<U...> | SystemTable<U...> | InitializerSystemFn<U...>
+--- @within Scheduler
+export type System<U...> =
+	SystemFn<U...>
+	| InitializerSystemFn<U...>
+	| SystemTable<U...>
 
-local function getSystem<U...>(system: any): SystemTable<U...>?
+local function getSystem<U...>(system: System<U...>): InternalSystem<U...>?
 	if type(system) == "function" then
 		return system
 	elseif type(system) == "table" and system.system then
@@ -22,12 +67,14 @@ local function getSystem<U...>(system: any): SystemTable<U...>?
 	end
 end
 
-local function getSystemName(system: any): string
+local function getSystemName<U...>(system: System<U...>): string
 	if type(system) == "table" and system.name then
 		return system.name
 	end
 
-	local fn = type(system) == "table" and system.system or system
+	local fn: AnyFunction = if type(system) == "table"
+		then system.system
+		else system
 
 	local name = debug.info(fn, "n")
 	if not name or string.len(name) == 0 then
@@ -38,17 +85,25 @@ local function getSystemName(system: any): string
 	return name
 end
 
-local function isPhase(phase: any): Phase?
+local function isSystem<U...>(system: unknown): InternalSystem<U...>?
+	if type(system) == "function" then
+		return system
+	else
+		return nil
+	end
+end
+
+local function isPhase(phase: unknown): Phase?
 	if type(phase) == "table" and phase._type == "phase" then
-		return phase
+		return phase :: Phase
 	else
 		return nil
 	end
 end
 
-local function isPipeline(pipeline: any): Pipeline?
+local function isPipeline(pipeline: unknown): Pipeline?
 	if type(pipeline) == "table" and pipeline._type == "pipeline" then
-		return pipeline
+		return pipeline :: Pipeline
 	else
 		return nil
 	end
@@ -86,11 +141,10 @@ local function disconnectEvent(connection: ConnectionLike)
 		return
 	elseif type(connection) == "table" then
 		for _, method in EVENT_DISCONNECT_METHODS do
-			if
-				connection[method]
-				and type(connection[method]) == "function"
-			then
-				connection[method](connection)
+			local connect: unknown = (connection :: any)[method]
+
+			if connect and connect == "function" then
+				(connect :: any)(connection)
 				return
 			end
 		end
@@ -119,31 +173,31 @@ export type SignalLike<U...> =
 		[any]: any,
 	}
 
-type GetConnectFn<U...> =
+type GetConnectFn =
 	-- RBXScriptSignal & nil
-	((RBXScriptSignal<U...>) -> ConnectFn<RBXScriptConnection, U...>)
+	(<U...>(RBXScriptSignal<U...>) -> ConnectFn<RBXScriptConnection, U...>)
 	-- Instance & RBXScriptSignal
 	-- Instance & string
-	& ((
+	& (<U...>(
 		Instance,
 		RBXScriptSignal<U...> | string
 	) -> ConnectFn<RBXScriptConnection, U...>)
 	-- SignalLike & nil
-	& ((SignalLike<U...>) -> ConnectFn<any, U...>)
+	& (<U...>(SignalLike<U...>) -> ConnectFn<any, U...>)
 	-- table & string
-	& ((GenericTable, string) -> ConnectFn<any, U...>)
+	& (<U...>(GenericTable, string) -> ConnectFn<any, U...>)
 	-- table & connectable method
-	& (<T>(
+	& (<T, U...>(
 		GenericTable,
 		(GenericTable, Callback<U...>, ...any) -> T
 	) -> ConnectFn<T, U...>)
 	-- connectable function
-	& (<T>((Callback<U...>, ...any) -> T) -> ConnectFn<T, U...>)
+	& (<T, U...>((Callback<U...>, ...any) -> T) -> ConnectFn<T, U...>)
 
 -- This function is inspired by useEvent in Matter, a library by evaera (https://github.com/evaera)
 -- License: Copyright (c) 2021 Eryn L. K., MIT License
 -- Source: https://github.com/matter-ecs/matter/blob/main/lib/hooks/useEvent.luau
-local function getConnectFunction(instance, event)
+local getConnectFn: GetConnectFn = function(instance: any, event: any): any
 	local eventInstance = instance
 
 	if typeof(event) == "RBXScriptSignal" or type(event) == "table" then
@@ -163,7 +217,7 @@ local function getConnectFunction(instance, event)
 	if type(eventInstance) == "table" then
 		if type(event) == "function" then
 			return function(callback)
-				return event(eventInstance, callback)
+				return (event :: any)(eventInstance, callback)
 			end
 		end
 
@@ -182,16 +236,17 @@ local function getConnectFunction(instance, event)
 end
 
 local function isValidEvent(instance, event)
-	return getConnectFunction(instance, event) ~= nil
+	return getConnectFn(instance, event) ~= nil
 end
 
 return {
 	getSystem = getSystem,
 	getSystemName = getSystemName,
+	isSystem = isSystem,
 	isPhase = isPhase,
 	isPipeline = isPipeline,
 	getEventIdentifier = getEventIdentifier,
 	isValidEvent = isValidEvent,
-	getConnectFunction = getConnectFunction :: GetConnectFn<...any>,
+	getConnectFn = getConnectFn,
 	disconnectEvent = disconnectEvent,
 }

package/src/hooks.luau

@@ -1,163 +0,0 @@
--- Super-duper experimental Plugin Hooks API
-
-local function systemAdd(scheduler, systemInfo)
-	local hooks = scheduler._hooks[scheduler.Hooks.SystemAdd]
-	local info = {
-		scheduler = scheduler,
-		system = systemInfo,
-	}
-
-	for _, hook in hooks do
-		local success, err = pcall(hook, info)
-		if not success then
-			warn("Unexpected error in hook:", err)
-		end
-	end
-end
-
-local function systemRemove(scheduler, systemInfo)
-	local hooks = scheduler._hooks[scheduler.Hooks.SystemRemove]
-	local info = {
-		scheduler = scheduler,
-		system = systemInfo,
-	}
-
-	for _, hook in hooks do
-		local success, err = pcall(hook, info)
-		if not success then
-			warn("Unexpected error in hook:", err)
-		end
-	end
-end
-
-local function systemCleanup(scheduler, systemInfo, cleanupError)
-	local hooks = scheduler._hooks[scheduler.Hooks.SystemCleanup]
-	local info = {
-		scheduler = scheduler,
-		system = systemInfo,
-		error = cleanupError,
-	}
-
-	for _, hook in hooks do
-		local success, err = pcall(hook, info)
-		if not success then
-			warn("Unexpected error in hook:", err)
-		end
-	end
-end
-
-local function systemReplace(scheduler, oldSystemInfo, newSystemInfo)
-	local hooks = scheduler._hooks[scheduler.Hooks.SystemReplace]
-	local info = {
-		scheduler = scheduler,
-		new = newSystemInfo,
-		old = oldSystemInfo,
-	}
-
-	for _, hook in hooks do
-		local success, err = pcall(hook, info)
-		if not success then
-			warn("Unexpected error in hook:", err)
-		end
-	end
-end
-
-local function systemCall(scheduler, hookName, systemInfo, nextFn)
-	local hooks = scheduler._hooks[scheduler.Hooks[hookName]]
-
-	if hooks then
-		for _, hook in hooks do
-			nextFn = hook({
-				scheduler = nil,
-				system = systemInfo,
-				nextFn = nextFn,
-			})
-
-			if not nextFn then
-				local source, line = debug.info(hook, "sl")
-				warn(
-					`{source}:{line}: Expected 'SystemCall' hook to return a function`
-				)
-			end
-		end
-	end
-
-	nextFn()
-end
-
-local function systemError(scheduler, systemInfo, err)
-	local hooks = scheduler._hooks[scheduler.Hooks["SystemError"]]
-
-	if hooks then
-		for _, hook in hooks do
-			hook({
-				scheduler = scheduler,
-				system = systemInfo,
-				error = err,
-			})
-		end
-	end
-end
-
-type PhaseAdd = {
-	scheduler: any,
-	phase: any,
-}
-
-local function phaseAdd(scheduler, phase)
-	local hooks = scheduler._hooks[scheduler.Hooks.PhaseAdd]
-	local info = {
-		scheduler = scheduler,
-		phase = phase,
-	}
-
-	for _, hook in hooks do
-		local success, err = pcall(hook, info)
-		if not success then
-			warn("Unexpected error in hook:", err)
-		end
-	end
-end
-
-local function phaseBegan(scheduler, phase)
-	local hooks = scheduler._hooks[scheduler.Hooks.PhaseBegan]
-	local info = {
-		scheduler = scheduler,
-		phase = phase,
-	}
-
-	for _, hook in hooks do
-		local success, err = pcall(hook, info)
-		if not success then
-			warn("Unexpected error in hook:", err)
-		end
-	end
-end
-
-local Hooks = {
-	SystemAdd = "SystemAdd",
-	SystemRemove = "SystemRemove",
-	SystemReplace = "SystemReplace",
-	SystemCleanup = "SystemCleanup",
-	SystemError = "SystemError",
-
-	OuterSystemCall = "OuterSystemCall",
-	InnerSystemCall = "InnerSystemCall",
-	SystemCall = "SystemCall",
-
-	PhaseAdd = "PhaseAdd",
-	PhaseBegan = "PhaseBegan",
-}
-
-return {
-	Hooks = Hooks,
-
-	systemAdd = systemAdd,
-	systemRemove = systemRemove,
-	systemReplace = systemReplace,
-	systemCleanup = systemCleanup,
-	systemCall = systemCall,
-	systemError = systemError,
-	phaseAdd = phaseAdd,
-	phaseBegan = phaseBegan,
-}