init.luau

--!strict

local Inst = {}

local function safeAssign(instance: Instance & any, key: string, value: any) -- horrible hack to avoid errors
	-- Prefer attributes for custom data
	if instance:GetAttribute(key) ~= nil or key:match("^%u") == nil then
		instance:SetAttribute(key, value)
		return
	end

    -- Avoid errors when assigning properties
	pcall(function() 
		(instance :: any)[key] = value
	end)
end

--[=[
	@class Inst
	A lightweight utility for creating, cloning, and organizing Roblox Instances safely.
]=]

--[=[
	Creates a new instance quickly with a name and optional parent.

	```lua
	local part = Inst.simple("Part", "MyPart", workspace)
	```
]=]
function Inst.simple<T>(classname: string, name: string, parent: Instance?): T
	local obj = Instance.new(classname) :: T & Instance
	obj.Name = name
	obj.Parent = parent
	return obj
end

--[=[
	Creates an instance with a table of properties applied safely.

	```lua
	local part = Inst.create("Part", {
		Size = Vector3.new(4,4,4),
		Anchored = true,
	}, workspace)
	```
]=]
function Inst.create<T>(
	classname: string,
	props: {[string]: any}?,
	parent: Instance?
): T
	local obj = Instance.new(classname) :: T & Instance

	if props then
		for k, v in props do
			safeAssign(obj, k, v)
		end
	end

	obj.Parent = parent
	return obj
end

--[=[
	Clones a template instance and optionally applies new properties.

	```lua
	local copy = Inst.cloneWith(template, { Color = Color3.new(1,0,0) }, workspace)
	```
]=]
function Inst.cloneWith<T>(
	template: T & Instance,
	props: {[string]: any}?,
	parent: Instance?
): T
	local obj = template:Clone()

	if props then
		for k, v in props do
			safeAssign(obj, k, v)
		end
	end

	obj.Parent = parent
	return obj
end

--[=[
	Parents multiple children to the same instance.

	```lua
	Inst.children(model, { part1, part2, part3 })
	```
]=]
function Inst.children(parent: Instance, children: {Instance})
	for _, child in children do
		child.Parent = parent
	end
	return parent
end

--[=[
	Creates multiple instances at once.

	```lua
	local parts = Inst.batch("Part", 10, { Anchored = true }, workspace)
	```
]=]
function Inst.batch(
	classname: string,
	amount: number,
	props: {[string]: any}?,
	parent: Instance?
): {Instance}
	local list = {}

	for i = 1, amount do
		list[i] = Inst.create(classname, props, parent)
	end

	return list
end

--[=[
	Finds the first descendant with the given name.

	```lua
	local button = Inst.firstDescendant(gui, "SubmitButton")
	```
]=]
function Inst.firstDescendant(parent: Instance, name: string): Instance?
	for _, desc in parent:GetDescendants() do
		if desc.Name == name then
			return desc
		end
	end
	return nil
end

--[=[
	Welds two parts together using a WeldConstraint.

	```lua
	Inst.weldParts(partA, partB)
	```
]=]
function Inst.weldParts(part0: BasePart, part1: BasePart)
	local weld = Instance.new("WeldConstraint")
	weld.Part0 = part0
	weld.Part1 = part1
	weld.Parent = part0
	return weld
end

--[=[
	Welds multiple parts together to the first part in the list.

	```lua
	Inst.weldAll({ partA, partB, partC })
	```
]=]
function Inst.weldAll(parts: {BasePart})
	for i = 2, #parts do
		Inst.weldParts(parts[1], parts[i])
	end
end

--[=[
	Assigns a property to an instance safely.

	```lua
	Inst.assignSafe(part, "Color", Color3.new(0,1,0))
	```
]=]
function Inst.assignSafe(instance: Instance, key: string, value: any)
	safeAssign(instance, key, value)
end

--[=[
	Welds two parts together and aligns their CFrames.

	```lua
	Inst.weld(partA, partB)
	```
]=]
function Inst.weld(part0: BasePart, part1: BasePart)
	part1.CFrame = part0.CFrame
	return Inst.weldParts(part0, part1)
end

--[=[
	Clones a part, aligns it to another part, and welds them together.

	```lua
	local newPart = Inst.cloneAndWeld(partA, partB)
	```
]=]
function Inst.cloneAndWeld(origin: BasePart, clone: BasePart)
	local clonedPart = clone:Clone() :: BasePart
	clonedPart.CFrame = origin.CFrame
	clonedPart.Parent = origin.Parent
	Inst.weldParts(origin, clonedPart)
	return clonedPart
end

--[=[
	Assigns multiple attributes to an instance from a table.

	```lua
	Inst.assignAttributesFromTable(part, { Health = 100, IsActive = true })
	```
]=]
function Inst.assignAttributesFromTable(instance: Instance, attrs: {[string]: any})
	for key, value in attrs do
		instance:SetAttribute(key, value)
	end
end

--[=[
	Assigns multiple properties to an instance from a table.

	```lua
	Inst.assignPropertiesFromTable(part, { Size = Vector3.new(2,2,2), Anchored = false })
	```
]=]
function Inst.assignPropertiesFromTable(instance: Instance, props: {[string]: any})
	for key, value in props do
		(instance :: any)[key] = value
	end
end

function Inst.instanceOf(instance: Instance, className: string): boolean
	return instance:IsA(className)
end

local destroyFunc = game.Destroy

--[=[
	Adds an instance to Debris with a specified delay.

	```lua
	Inst.debrisAdd(part, 5) -- Destroys part after 5 seconds
	```
]=]
function Inst.debrisAdd(instance: Instance, delay: number): Instance
	task.delay(delay, destroyFunc, instance)
	return instance
end

return Inst