@quenty/steputils 3.7.0 → 3.7.2

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.7.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.7.1...@quenty/steputils@3.7.2) (2026-08-14)
+
+**Note:** Version bump only for package @quenty/steputils
+
+## [3.7.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.7.0...@quenty/steputils@3.7.1) (2026-07-25)
+
+### Bug Fixes
+
+- Fix things ([de8a3b5](https://github.com/Quenty/NevermoreEngine/commit/de8a3b5fbe2aa839f6fc928d4052405d3a13cd71))
+
 # [3.7.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.3...@quenty/steputils@3.7.0) (2026-07-23)
 
 ### Bug Fixes

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 80583370987435,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/steputils",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "description": "Binds animations into step, where the animation only runs as needed",
   "keywords": [
     "Roblox",
@@ -27,8 +27,13 @@
   "contributors": [
     "Quenty"
   ],
+  "dependencies": {
+    "@quenty/loader": "10.11.1",
+    "@quenty/nevermore-test-runner": "1.5.1",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
+  "gitHead": "f084360c3729ea424d49d9bc42f8f0d1c128fa82"
 }

package/src/Shared/StepUtils.lua

@@ -36,6 +36,31 @@ function StepUtils.getAnimationStepSignal(): RBXScriptSignal
 	end
 end
 
+--[=[
+	Returns the signal per-frame bookkeeping should run on: [RunService.Stepped] (the physics
+	pre-step) on a running DataModel, falling back to [RunService.Heartbeat] on a non-running one
+	(headless test runs, edit mode) where Stepped never fires.
+
+	Unlike [StepUtils.getAnimationStepSignal] this does not branch to RenderStepped on the client,
+	so both realms step at the same point in the frame. Prefer it for work that is not driving
+	visuals -- rescoring, polling, cache invalidation -- and that would otherwise silently stop
+	running outside a live game.
+
+	:::caution
+	Stepped fires `(time, deltaTime)` but Heartbeat fires `(deltaTime)`. Do not assume the first
+	argument is deltaTime when connecting directly to this signal.
+	:::
+
+	@return RBXScriptSignal
+]=]
+function StepUtils.getSteppedSignal(): RBXScriptSignal
+	if RunService:IsRunning() then
+		return RunService.Stepped
+	else
+		return RunService.Heartbeat
+	end
+end
+
 --[=[
 	Binds the given update function to [StepUtils.getAnimationStepSignal].
 

package/src/Shared/StepUtils.spec.lua

@@ -0,0 +1,635 @@
+--!strict
+--[[
+	@class StepUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local RunService = game:GetService("RunService")
+
+local Jest = require("Jest")
+local StepUtils = require("StepUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type Controller = {
+	newBindable: () -> BindableEvent,
+	bind: (RBXScriptSignal, (...any) -> boolean) -> ((...any) -> (), () -> ()),
+	bindRenderStep: ((...any) -> boolean) -> ((...any) -> (), () -> ()),
+	bindStepped: ((...any) -> boolean) -> ((...any) -> (), () -> ()),
+	track: (() -> ()) -> () -> (),
+	stepFrames: (number) -> (),
+	destroy: () -> (),
+}
+
+local function setup(): Controller
+	local instances: { Instance } = {}
+	local cleanups: { () -> () } = {}
+
+	local function track(cleanup: () -> ()): () -> ()
+		table.insert(cleanups, cleanup)
+		return cleanup
+	end
+
+	local controller: Controller = {
+		newBindable = function()
+			local bindable = Instance.new("BindableEvent")
+			table.insert(instances, bindable)
+			return bindable
+		end,
+
+		bind = function(signal, update)
+			local connect, disconnect = StepUtils.bindToSignal(signal, update)
+			track(disconnect)
+			return connect, disconnect
+		end,
+
+		bindRenderStep = function(update)
+			local connect, disconnect = StepUtils.bindToRenderStep(update)
+			track(disconnect)
+			return connect, disconnect
+		end,
+
+		bindStepped = function(update)
+			local connect, disconnect = StepUtils.bindToStepped(update)
+			track(disconnect)
+			return connect, disconnect
+		end,
+
+		track = track,
+
+		stepFrames = function(count: number)
+			for _ = 1, count do
+				task.wait()
+			end
+		end,
+
+		destroy = function()
+			for _, cleanup in cleanups do
+				cleanup()
+			end
+			for _, inst in instances do
+				inst:Destroy()
+			end
+		end,
+	}
+
+	return controller
+end
+
+describe("StepUtils.getAnimationStepSignal", function()
+	it("returns a signal", function()
+		local controller = setup()
+
+		expect(typeof(StepUtils.getAnimationStepSignal())).toBe("RBXScriptSignal")
+
+		controller.destroy()
+	end)
+
+	it("falls back to Heartbeat off a running client", function()
+		local controller = setup()
+
+		expect(StepUtils.getAnimationStepSignal()).toBe(RunService.Heartbeat)
+
+		controller.destroy()
+	end)
+
+	it("returns a signal that actually fires here", function()
+		local controller = setup()
+
+		local fired = false
+		local conn = StepUtils.getAnimationStepSignal():Connect(function()
+			fired = true
+		end)
+		controller.track(function()
+			conn:Disconnect()
+		end)
+
+		controller.stepFrames(2)
+
+		expect(fired).toBe(true)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.getSteppedSignal", function()
+	it("returns a signal", function()
+		local controller = setup()
+
+		expect(typeof(StepUtils.getSteppedSignal())).toBe("RBXScriptSignal")
+
+		controller.destroy()
+	end)
+
+	it("falls back to Heartbeat on a non-running DataModel", function()
+		local controller = setup()
+
+		expect(StepUtils.getSteppedSignal()).toBe(RunService.Heartbeat)
+		expect(StepUtils.getSteppedSignal()).never.toBe(RunService.Stepped)
+
+		controller.destroy()
+	end)
+
+	it("returns a signal that actually fires here", function()
+		local controller = setup()
+
+		local fired = false
+		local conn = StepUtils.getSteppedSignal():Connect(function()
+			fired = true
+		end)
+		controller.track(function()
+			conn:Disconnect()
+		end)
+
+		controller.stepFrames(2)
+
+		expect(fired).toBe(true)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.bindToSignal", function()
+	it("invokes the update immediately on connect", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("does not connect when the first update returns false", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("keeps invoking the update while it returns true", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return calls < 3
+		end)
+
+		connect()
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(3)
+
+		controller.destroy()
+	end)
+
+	it("stops invoking the update once it returns false", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return calls < 2
+		end)
+
+		connect()
+		bindable:Fire()
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(2)
+
+		controller.destroy()
+	end)
+
+	it("forwards the connect arguments to every later update", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local seen = {}
+		local connect = controller.bind(bindable.Event, function(arg)
+			table.insert(seen, arg)
+			return #seen < 3
+		end)
+
+		connect("self")
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(seen).toEqual({ "self", "self", "self" })
+
+		controller.destroy()
+	end)
+
+	it("ignores the signal's own arguments", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local seen = {}
+		local connect = controller.bind(bindable.Event, function(arg)
+			table.insert(seen, { value = arg })
+			return #seen < 2
+		end)
+
+		connect()
+		bindable:Fire("fromSignal")
+
+		expect(seen).toEqual({ { value = nil }, { value = nil } })
+
+		controller.destroy()
+	end)
+
+	it("ignores a repeated connect while already connected", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return true
+		end)
+
+		connect()
+		connect()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("reconnects after an explicit disconnect", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect, disconnect = controller.bind(bindable.Event, function()
+			calls += 1
+			return true
+		end)
+
+		connect()
+		disconnect()
+		bindable:Fire()
+		expect(calls).toBe(1)
+
+		connect()
+		bindable:Fire()
+
+		expect(calls).toBe(3)
+
+		controller.destroy()
+	end)
+
+	it("tolerates disconnect before connect and repeated disconnects", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local _connect, disconnect = controller.bind(bindable.Event, function()
+			return true
+		end)
+
+		expect(function()
+			disconnect()
+			disconnect()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on something that is not a signal", function()
+		local controller = setup()
+
+		expect(function()
+			(StepUtils :: any).bindToSignal({}, function()
+				return false
+			end)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function update", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		expect(function()
+			(StepUtils :: any).bindToSignal(bindable.Event, "update")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.bindToRenderStep", function()
+	it("drives the update off the animation step signal", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect = controller.bindRenderStep(function()
+			calls += 1
+			return calls < 3
+		end)
+
+		connect()
+		controller.stepFrames(5)
+
+		expect(calls).toBe(3)
+
+		controller.destroy()
+	end)
+
+	it("does not bind when the first update returns false", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect = controller.bindRenderStep(function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+		controller.stepFrames(3)
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("stops driving the update after disconnect", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect, disconnect = controller.bindRenderStep(function()
+			calls += 1
+			return true
+		end)
+
+		connect()
+		controller.stepFrames(2)
+		disconnect()
+
+		local afterDisconnect = calls
+		controller.stepFrames(3)
+
+		expect(calls).toBe(afterDisconnect)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.bindToStepped", function()
+	it("invokes the update immediately on connect", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect = controller.bindStepped(function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("tolerates disconnect before connect", function()
+		local controller = setup()
+
+		local _connect, disconnect = controller.bindStepped(function()
+			return true
+		end)
+
+		expect(function()
+			disconnect()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.deferWait", function()
+	it("resumes only after already-queued deferrals run", function()
+		local controller = setup()
+
+		local order = {}
+		task.defer(function()
+			table.insert(order, "deferred")
+		end)
+
+		StepUtils.deferWait()
+		table.insert(order, "resumed")
+
+		expect(order).toEqual({ "deferred", "resumed" })
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtEvent", function()
+	it("invokes the function on the next event", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		controller.track(StepUtils.onceAtEvent(bindable.Event, function()
+			calls += 1
+		end))
+
+		bindable:Fire()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("passes the event arguments through", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local seen: any = nil
+		controller.track(StepUtils.onceAtEvent(bindable.Event, function(value: any)
+			seen = value
+		end))
+
+		bindable:Fire("payload")
+
+		expect(seen).toBe("payload")
+
+		controller.destroy()
+	end)
+
+	it("only invokes the function once", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		controller.track(StepUtils.onceAtEvent(bindable.Event, function()
+			calls += 1
+		end))
+
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("does not invoke the function once cancelled", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local cancel = StepUtils.onceAtEvent(bindable.Event, function()
+			calls += 1
+		end)
+
+		cancel()
+		bindable:Fire()
+
+		expect(calls).toBe(0)
+
+		controller.destroy()
+	end)
+
+	it("tolerates cancelling after the function ran", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local cancel = StepUtils.onceAtEvent(bindable.Event, function() end)
+		bindable:Fire()
+
+		expect(function()
+			cancel()
+			cancel()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		expect(function()
+			(StepUtils :: any).onceAtEvent(bindable.Event, "func")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtRenderStepped", function()
+	it("invokes the function once on the animation step signal", function()
+		local controller = setup()
+
+		local calls = 0
+		controller.track(StepUtils.onceAtRenderStepped(function()
+			calls += 1
+		end))
+
+		controller.stepFrames(3)
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("does not invoke the function once cancelled", function()
+		local controller = setup()
+
+		local calls = 0
+		local cancel = StepUtils.onceAtRenderStepped(function()
+			calls += 1
+		end)
+
+		cancel()
+		controller.stepFrames(3)
+
+		expect(calls).toBe(0)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtStepped", function()
+	it("returns a cancel function that is safe to call twice", function()
+		local controller = setup()
+
+		local calls = 0
+		local cancel = StepUtils.onceAtStepped(function()
+			calls += 1
+		end)
+
+		expect(function()
+			cancel()
+			cancel()
+		end).never.toThrow()
+		expect(calls).toBe(0)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtRenderPriority", function()
+	it("returns a cancel function that is safe to call twice", function()
+		local controller = setup()
+
+		local cancel = StepUtils.onceAtRenderPriority(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(function()
+			cancel()
+			cancel()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-number priority", function()
+		local controller = setup()
+
+		expect(function()
+			(StepUtils :: any).onceAtRenderPriority("high", function() end)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function", function()
+		local controller = setup()
+
+		expect(function()
+			(StepUtils :: any).onceAtRenderPriority(100, "func")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/Shared/onRenderStepFrame.spec.lua

@@ -0,0 +1,98 @@
+--!strict
+--[[
+	@class onRenderStepFrame.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local onRenderStepFrame = require("onRenderStepFrame")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type Controller = {
+	bind: (number, () -> ()) -> () -> (),
+	destroy: () -> (),
+}
+
+local function setup(): Controller
+	local unbinds: { () -> () } = {}
+
+	local controller: Controller = {
+		bind = function(priority: number, callback: () -> ())
+			local unbind = onRenderStepFrame(priority, callback)
+			table.insert(unbinds, unbind)
+			return unbind
+		end,
+
+		destroy = function()
+			for _, unbind in unbinds do
+				unbind()
+			end
+		end,
+	}
+
+	return controller
+end
+
+describe("onRenderStepFrame", function()
+	it("returns an unbind function", function()
+		local controller = setup()
+
+		local unbind = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(type(unbind)).toBe("function")
+
+		controller.destroy()
+	end)
+
+	it("tolerates a repeated unbind", function()
+		local controller = setup()
+
+		local unbind = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(function()
+			unbind()
+			unbind()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("binds each call under its own key", function()
+		local controller = setup()
+
+		local first = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+		local second = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(second).never.toBe(first)
+		expect(function()
+			first()
+			second()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-number priority", function()
+		local controller = setup()
+
+		expect(function()
+			(onRenderStepFrame :: any)("high", function() end)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function callback", function()
+		local controller = setup()
+
+		expect(function()
+			(onRenderStepFrame :: any)(100, "callback")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/Shared/onSteppedFrame.spec.lua

@@ -0,0 +1,85 @@
+--!strict
+--[[
+	@class onSteppedFrame.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local onSteppedFrame = require("onSteppedFrame")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type Controller = {
+	bind: (() -> ()) -> RBXScriptConnection,
+	destroy: () -> (),
+}
+
+local function setup(): Controller
+	local connections: { RBXScriptConnection } = {}
+
+	local controller: Controller = {
+		bind = function(callback)
+			local conn = onSteppedFrame(callback)
+			table.insert(connections, conn)
+			return conn
+		end,
+
+		destroy = function()
+			for _, conn in connections do
+				conn:Disconnect()
+			end
+		end,
+	}
+
+	return controller
+end
+
+describe("onSteppedFrame", function()
+	it("returns a live connection", function()
+		local controller = setup()
+
+		local conn = controller.bind(function() end)
+
+		expect(typeof(conn)).toBe("RBXScriptConnection")
+		expect(conn.Connected).toBe(true)
+
+		controller.destroy()
+	end)
+
+	it("goes dead once disconnected", function()
+		local controller = setup()
+
+		local conn = controller.bind(function() end)
+		conn:Disconnect()
+
+		expect(conn.Connected).toBe(false)
+
+		controller.destroy()
+	end)
+
+	it("tolerates a repeated disconnect", function()
+		local controller = setup()
+
+		local conn = controller.bind(function() end)
+
+		expect(function()
+			conn:Disconnect()
+			conn:Disconnect()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function", function()
+		local controller = setup()
+
+		expect(function()
+			(onSteppedFrame :: any)("func")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}

package/test/default.project.json

@@ -0,0 +1,25 @@
+{
+  "name": "StepUtilsTest",
+  "globIgnorePaths": [
+    "**/.package-lock.json",
+    "**/.pnpm",
+    "**/.pnpm-workspace-state-v1.json",
+    "**/.modules.yaml",
+    "**/.ignored",
+    "**/.ignored_*"
+  ],
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "steputils": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,14 @@
+--!nonstrict
+--[[
+	@class ServerMain
+]]
+
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.steputils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+NevermoreTestRunnerUtils.runTestsIfNeededAsync(root)