@quenty/spring 10.8.1 → 10.8.2

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.8.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/spring@10.8.1...@quenty/spring@10.8.2) (2025-04-05)
+
+
+### Bug Fixes
+
+* Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
+
+
+
+
+
 ## [10.8.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/spring@10.8.0...@quenty/spring@10.8.1) (2025-03-21)
 
 **Note:** Version bump only for package @quenty/spring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/spring",
-  "version": "10.8.1",
+  "version": "10.8.2",
   "description": "Spring implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -29,8 +29,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@quenty/ducktype": "^5.8.1",
-    "@quenty/loader": "^10.8.0"
+    "@quenty/ducktype": "^5.8.2",
+    "@quenty/loader": "^10.8.1"
   },
-  "gitHead": "6b7c3e15e60cdb185986207b574e2b5591261e7a"
+  "gitHead": "78c3ac0ab08dd18085b6e6e6e4f745e76ed99f68"
 }

package/src/Shared/LinearValue.lua

@@ -1,3 +1,4 @@
+--!nocheck
 --[=[
 	Represents a value that can operate in linear space
 
@@ -12,6 +13,14 @@ local LinearValue = {}
 LinearValue.ClassName = "LinearValue"
 LinearValue.__index = LinearValue
 
+export type LinearValue<T> = typeof(setmetatable(
+	{} :: {
+		_constructor: (...number) -> T,
+		_values: { number },
+	},
+	LinearValue
+))
+
 --[=[
 	Constructs a new LinearValue object.
 
@@ -19,10 +28,10 @@ LinearValue.__index = LinearValue
 	@param values ({ number })
 	@return LinearValue<T>
 ]=]
-function LinearValue.new(constructor, values)
+function LinearValue.new<T>(constructor: (...number) -> T, values: { number }): LinearValue<T>
 	return setmetatable({
-		_constructor = constructor;
-		_values = values;
+		_constructor = constructor,
+		_values = values,
 	}, LinearValue)
 end
 
@@ -32,28 +41,32 @@ end
 	@param value any -- A value to check
 	@return boolean -- True if a linear value, false otherwise
 ]=]
-function LinearValue.isLinear(value)
+function LinearValue.isLinear(value: any): boolean
 	return DuckTypeUtils.isImplementation(LinearValue, value)
 end
 
-local function convertUDim2(scaleX, offsetX, scaleY, offsetY)
+local function convertUDim2(scaleX: number, offsetX: number, scaleY: number, offsetY: number): UDim2
 	-- Roblox UDim2.new(0, 9.999, 0, 9.999) rounds to UDim2.new(0, 9, 0, 9) which means small floating point
 	-- errors can cause shaking UI.
 
 	return UDim2.new(scaleX, math.round(offsetX), scaleY, math.round(offsetY))
 end
 
-local function convertUDim(scale, offset)
+local function convertUDim(scale: number, offset: number): UDim
 	-- Roblox UDim.new(0, 9.999) rounds to UDim.new(0, 9) which means small floating point
 	-- errors can cause shaking UI.
 
 	return UDim.new(scale, math.round(offset))
 end
 
-local function convertBoolean(value)
+local function convertBoolean(value: number): boolean
 	return value ~= 0
 end
 
+local function convertColor3(r: number, g: number, b: number): Color3
+	return Color3.new(r, g, b)
+end
+
 --[=[
 	Converts an arbitrary value to a LinearValue if Roblox has not defined this value
 	for multiplication and addition.
@@ -61,13 +74,16 @@ end
 	@param value T
 	@return LinearValue<T> | T
 ]=]
-function LinearValue.toLinearIfNeeded(value)
+function LinearValue.toLinearIfNeeded<T>(value: any): LinearValue<any>
 	if typeof(value) == "Color3" then
-		return LinearValue.new(Color3.new, {value.r, value.g, value.b})
+		return LinearValue.new(convertColor3, { value.R, value.G, value.B })
 	elseif typeof(value) == "UDim2" then
-		return LinearValue.new(convertUDim2, {value.X.Scale, math.round(value.X.Offset), value.Y.Scale, math.round(value.Y.Offset)})
+		return LinearValue.new(
+			convertUDim2,
+			{ value.X.Scale, math.round(value.X.Offset), value.Y.Scale, math.round(value.Y.Offset) }
+		)
 	elseif typeof(value) == "UDim" then
-		return LinearValue.new(convertUDim, {value.Scale, math.round(value.Offset)})
+		return LinearValue.new(convertUDim, { value.Scale, math.round(value.Offset) })
 	elseif type(value) == "boolean" then
 		return LinearValue.new(convertBoolean, { value and 1 or 0 })
 	else
@@ -81,7 +97,7 @@ end
 	@param value LinearValue<T> | any
 	@return T | any
 ]=]
-function LinearValue.fromLinearIfNeeded(value)
+function LinearValue.fromLinearIfNeeded<T>(value: LinearValue<T> | any): any
 	if LinearValue.isLinear(value) then
 		return value:ToBaseValue()
 	else
@@ -94,24 +110,24 @@ end
 
 	@return T
 ]=]
-function LinearValue:ToBaseValue()
+function LinearValue:ToBaseValue<T>(): T
 	return self._constructor(unpack(self._values))
 end
 
-local function operation(func)
-	return function(a, b)
+local function operation(func: (number, number) -> number)
+	return function(a: LinearValue<any>, b: LinearValue<any>)
 		if LinearValue.isLinear(a) and LinearValue.isLinear(b) then
 			assert(a._constructor == b._constructor, "a is not the same type of linearValue as b")
 
 			local values = {}
-			for i=1, #a._values do
+			for i = 1, #a._values do
 				values[i] = func(a._values[i], b._values[i])
 			end
 			return LinearValue.new(a._constructor, values)
 		elseif LinearValue.isLinear(a) then
 			if type(b) == "number" then
 				local values = {}
-				for i=1, #a._values do
+				for i = 1, #a._values do
 					values[i] = func(a._values[i], b)
 				end
 				return LinearValue.new(a._constructor, values)
@@ -121,7 +137,7 @@ local function operation(func)
 		elseif LinearValue.isLinear(b) then
 			if type(a) == "number" then
 				local values = {}
-				for i=1, #b._values do
+				for i = 1, #b._values do
 					values[i] = func(a, b._values[i])
 				end
 				return LinearValue.new(b._constructor, values)
@@ -139,11 +155,11 @@ end
 
 	@return number -- The magnitude of the linear value.
 ]=]
-function LinearValue:GetMagnitude()
-	local dot = 0
-	for i=1, #self._values do
-		local value = self._values[i]
-		dot = dot + value*value
+function LinearValue:GetMagnitude(): number
+	local dot: number = 0
+	for i = 1, #self._values do
+		local value: number = self._values[i]
+		dot = dot + value * value
 	end
 	return math.sqrt(dot)
 end
@@ -155,10 +171,10 @@ end
 	@readonly
 	@within LinearValue
 ]=]
-function LinearValue:__index(key)
+function LinearValue.__index<T>(self: LinearValue<T>, key: string): any
 	if LinearValue[key] then
 		return LinearValue[key]
-	elseif key == "magnitude" then
+	elseif key == "magnitude" or key == "Magnitude" then
 		return self:GetMagnitude()
 	else
 		return nil
@@ -181,7 +197,7 @@ LinearValue.__div = operation(function(a, b)
 	return a / b
 end)
 
-function LinearValue:__eq(a, b)
+function LinearValue:__eq<T>(a: LinearValue<T>, b: LinearValue<T>): boolean
 	if LinearValue.isLinear(a) and LinearValue.isLinear(b) then
 		if #a._values ~= #b._values then
 			return false

package/src/Shared/Spring.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	A physical model of a spring, useful in many applications.
 
@@ -27,6 +28,30 @@
 	@class Spring
 ]=]
 local Spring = {}
+Spring.__index = Spring
+
+export type SpringClock = () -> number
+
+export type Spring<T> = typeof(setmetatable(
+	{} :: {
+		Position: T,
+		Velocity: T,
+		Target: T,
+		Damper: number,
+		Speed: number,
+		Clock: SpringClock,
+
+		_position0: T,
+		_velocity0: T,
+		_time0: number,
+		_target: T,
+		_damper: number,
+		_speed: number,
+		_clock: SpringClock,
+		_positionVelocity: (self: Spring<T>, now: number) -> (T, T),
+	},
+	Spring
+))
 
 --[=[
 	Constructs a new Spring at the position and target specified, of type T.
@@ -46,18 +71,19 @@ local Spring = {}
 	@param clock? () -> number -- The clock function is optional, and is used to update the spring
 	@return Spring<T>
 ]=]
-function Spring.new(initial, clock)
-	local target = initial or 0
-	clock = clock or os.clock
+function Spring.new<T>(initial: T?, clock: SpringClock?): Spring<T>
+	local p0 = initial or 0
+	local springClock = clock or os.clock
+
 	return setmetatable({
-		_clock = clock;
-		_time0 = clock();
-		_position0 = target;
-		_velocity0 = 0*target;
-		_target = target;
-		_damper = 1;
-		_speed = 1;
-	}, Spring)
+		_clock = springClock,
+		_time0 = springClock(),
+		_position0 = p0,
+		_velocity0 = 0 * (p0 :: any),
+		_target = p0,
+		_damper = 1,
+		_speed = 1,
+	}, Spring) :: any
 end
 
 --[=[
@@ -67,8 +93,8 @@ end
 	@param velocity T -- The velocity to impulse with
 	@return ()
 ]=]
-function Spring:Impulse(velocity)
-	self.Velocity = self.Velocity + velocity
+function Spring.Impulse<T>(self: Spring<T>, velocity: T)
+	self.Velocity = (self.Velocity :: any) + velocity
 end
 
 --[=[
@@ -76,9 +102,9 @@ end
 	@param delta number -- Time to skip forwards
 	@return ()
 ]=]
-function Spring:TimeSkip(delta)
+function Spring.TimeSkip<T>(self: Spring<T>, delta: number)
 	local now = self._clock()
-	local position, velocity = self:_positionVelocity(now+delta)
+	local position, velocity = self:_positionVelocity(now + delta)
 	self._position0 = position
 	self._velocity0 = velocity
 	self._time0 = now
@@ -90,11 +116,11 @@ end
 	@param value T -- The target to set
 	@param doNotAnimate boolean? -- Whether or not to animate
 ]=]
-function Spring:SetTarget(value, doNotAnimate)
+function Spring.SetTarget<T>(self: Spring<T>, value: T, doNotAnimate: boolean?)
 	if doNotAnimate then
 		local now = self._clock()
 		self._position0 = value
-		self._velocity0 = 0*value
+		self._velocity0 = 0 * (value :: any)
 		self._target = value
 		self._time0 = now
 	else
@@ -183,7 +209,7 @@ end
 	@prop Clock () -> number
 	@within Spring
 ]=]
-function Spring:__index(index)
+(Spring :: any).__index = function<T>(self: Spring<T>, index: any): any
 	if Spring[index] then
 		return Spring[index]
 	elseif index == "Value" or index == "Position" or index == "p" then
@@ -205,7 +231,7 @@ function Spring:__index(index)
 	end
 end
 
-function Spring:__newindex(index, value)
+function Spring.__newindex<T>(self: Spring<T>, index, value)
 	local now = self._clock()
 
 	if index == "Value" or index == "Position" or index == "p" then
@@ -247,43 +273,43 @@ function Spring:__newindex(index, value)
 	end
 end
 
-function Spring:_positionVelocity(now)
+function Spring._positionVelocity<T>(self: Spring<T>, now: number): (T, T)
 	local p0 = self._position0
 	local v0 = self._velocity0
 	local p1 = self._target
-	local d = self._damper
-	local s = self._speed
+	local d: number = self._damper
+	local s: number = self._speed
 
-	local t = s*(now - self._time0)
-	local d2 = d*d
+	local t: number = s * (now - self._time0)
+	local d2 = d * d
 
 	local h, si, co
 	if d2 < 1 then
 		h = math.sqrt(1 - d2)
-		local ep = math.exp(-d*t)/h
-		co, si = ep*math.cos(h*t), ep*math.sin(h*t)
+		local ep = math.exp(-d * t) / h
+		co, si = ep * math.cos(h * t), ep * math.sin(h * t)
 	elseif d2 == 1 then
 		h = 1
-		local ep = math.exp(-d*t)/h
-		co, si = ep, ep*t
+		local ep = math.exp(-d * t) / h
+		co, si = ep, ep * t
 	else
 		h = math.sqrt(d2 - 1)
-		local u = math.exp((-d + h)*t)/(2*h)
-		local v = math.exp((-d - h)*t)/(2*h)
+		local u = math.exp((-d + h) * t) / (2 * h)
+		local v = math.exp((-d - h) * t) / (2 * h)
 		co, si = u + v, u - v
 	end
 
-	local a0 = h*co + d*si
-	local a1 = 1 - (h*co + d*si)
-	local a2 = si/s
+	local a0: any = h * co + d * si
+	local a1: any = 1 - (h * co + d * si)
+	local a2: any = si / s
 
-	local b0 = -s*si
-	local b1 = s*si
-	local b2 = h*co - d*si
+	local b0: any = -s * si
+	local b1: any = s * si
+	local b2: any = h * co - d * si
 
-	return
-		a0*p0 + a1*p1 + a2*v0,
-		b0*p0 + b1*p1 + b2*v0
+	-- stylua: ignore
+	return a0 * p0 + a1 * p1 + a2 * v0,
+		b0 * p0 + b1 * p1 + b2 * v0
 end
 
 return Spring

package/src/Shared/SpringUtils.lua

@@ -1,15 +1,18 @@
+--!strict
 --[=[
 	Utility functions that are related to the Spring object
 	@class SpringUtils
 ]=]
 
-local EPSILON = 1e-6
-
 local require = require(script.Parent.loader).load(script)
+
 local LinearValue = require("LinearValue")
+local _Spring = require("Spring")
 
 local SpringUtils = {}
 
+local EPSILON = 1e-6
+
 --[=[
 	Utility function that returns whether or not a spring is animating based upon
 	velocity and closeness to target, and as the second value, the value that should be
@@ -19,21 +22,21 @@ local SpringUtils = {}
 	@param epsilon number? -- Optional epsilon
 	@return boolean, T
 ]=]
-function SpringUtils.animating(spring, epsilon)
-	epsilon = epsilon or EPSILON
+function SpringUtils.animating<T>(spring: _Spring.Spring<T>, epsilon: number?): (boolean, T)
+	local thisEpsilon = epsilon or EPSILON
 
 	local position = spring.Position
 	local target = spring.Target
 
 	local animating
 	if type(target) == "number" then
-		animating = math.abs(spring.Position - spring.Target) > epsilon
-			or math.abs(spring.Velocity) > epsilon
+		animating = math.abs((spring :: any).Position - (spring :: any).Target) > thisEpsilon
+			or math.abs((spring :: any).Velocity) > thisEpsilon
 	else
 		local rbxtype = typeof(target)
 		if rbxtype == "Vector3" or rbxtype == "Vector2" or LinearValue.isLinear(target) then
-			animating = (spring.Position - spring.Target).magnitude > epsilon
-				or spring.Velocity.magnitude > epsilon
+			animating = ((spring :: any).Position - (spring :: any).Target).magnitude > thisEpsilon
+				or (spring :: any).Velocity.magnitude > thisEpsilon
 		else
 			error("Unknown type")
 		end
@@ -42,7 +45,7 @@ function SpringUtils.animating(spring, epsilon)
 	if animating then
 		return true, position
 	else
-		-- We need to return the target so we use the actual target value (i.e. pretend like the spring is asleep)
+		-- We need to return the target so we use the actual target value (i.e. pretend like the (spring :: any) is asleep)
 		return false, target
 	end
 end
@@ -55,12 +58,12 @@ end
 	@param speed number
 	@return T
 ]=]
-function SpringUtils.getVelocityAdjustment(velocity, dampen, speed)
+function SpringUtils.getVelocityAdjustment<T>(velocity: T, dampen: number, speed: number): T
 	assert(velocity, "Bad velocity")
 	assert(dampen, "Bad dampen")
 	assert(speed, "Bad speed")
 
-	return velocity*(2*dampen/speed)
+	return (velocity :: any) * (2 * dampen / speed)
 end
 
 --[=[
@@ -70,7 +73,7 @@ end
 	@param value T
 	@return LinearValue<T> | T
 ]=]
-function SpringUtils.toLinearIfNeeded(value)
+function SpringUtils.toLinearIfNeeded<T>(value: T): LinearValue.LinearValue<T> | T
 	return LinearValue.toLinearIfNeeded(value)
 end
 
@@ -80,7 +83,7 @@ end
 	@param value LinearValue<T> | any
 	@return T | any
 ]=]
-function SpringUtils.fromLinearIfNeeded(value)
+function SpringUtils.fromLinearIfNeeded<T>(value: LinearValue.LinearValue<T> | T): T
 	return LinearValue.fromLinearIfNeeded(value)
 end