Skip to main content

Binder

Bind class to Roblox Instance

-- Setup a class!
local MyClass = {}
MyClass.__index = MyClass

function MyClass.new(robloxInstance)
	print("New tagged instance of ", robloxInstance)
	return setmetatable({}, MyClass)
end

function MyClass:Destroy()
	print("Cleaning up")
	setmetatable(self, nil)
end

-- bind to every instance with tag of "TagName"!
local binder = Binder.new("TagName", MyClass)
binder:Start() -- listens for new instances and connects events

Types

BinderContructor

type BinderContructor = (
...any
) → T | {new(
...any
)} | {
Create(self,
...any)
}

Constructor for a binder

Functions

new

Binder.new(
tagNamestring,--

Name of the tag to bind to. This uses CollectionService's tag system

constructorBinderContructor,
...any--

Variable arguments that will be passed into the constructor

) → Binder<T>

Constructs a new binder object.

local binder = Binder.new("Bird", function(inst)
	print("Wow, a new bird!", inst)

	return {
		Destroy = function()
			print("Uh oh, the bird is gone!")
		end;
	}
end)
binder:Start()

isBinder

Binder.isBinder(valueany) → booleantrueorfalse,whetherornotitisavalue

Retrieves whether or not the given value is a binder.

Init

Binder:Init(...any) → ()

Initializes the Binder. Designed to be done via ServiceBag.

Start

Binder:Start() → ()

Listens for new instances and connects to the GetInstanceAddedSignal() and removed signal!

GetTag

Binder:GetTag() → string

Returns the tag name that the binder has.

GetConstructor

Binder:GetConstructor() → BinderContructor

Returns whatever was set for the construtor. Used for meta-analysis of the binder, such as extracting if parameters are allowed.

Observe

Binder:Observe(instanceInstance) → Observable<T | nil>

Observes the current value of the instance

ObserveAllBrio

Binder:ObserveAllBrio() → Observable<Brio<T>>

Observes all entries in the binder

ObserveBrio

Binder:ObserveBrio(instanceInstance) → Observable<Brio<T>>

Observes a bound class on a given instance.

ObserveInstance

Binder:ObserveInstance(
instInstance,
callbackfunction
) → function--

Cleanup function

Fired when added, and then after removal, but before destroy!

info

This is before Rx so it doesn't follow the same Rx pattern. See Binder.Observe for an Rx compatible interface.

GetClassAddedSignal

Binder:GetClassAddedSignal() → Signal<T>

Returns a new signal that will fire whenever a class is bound to the binder

local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder

birdBinder:GetClassAddedSignal():Connect(function(bird)
	bird:Squack() -- Make the bird squack when it's first spawned
end)

-- Load all birds
birdBinder:Start()

GetClassRemovingSignal

Binder:GetClassRemovingSignal() → Signal<T>

Returns a new signal that will fire whenever a class is removing from the binder.

GetClassRemovedSignal

Binder:GetClassRemovedSignal() → Signal<T>

Returns a new signal that will fire whenever a class is removed from the binder.

GetAll

Binder:GetAll() → {T}

Returns all of the classes in a new table.

local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder

-- Update every bird every frame
RunService.Stepped:Connect(function()
	for _, bird in pairs(birdBinder:GetAll()) do
		bird:Update()
	end
end)

birdBinder:Start()

GetAllSet

Binder:GetAllSet() → {[T]boolean}

Faster method to get all items in a binder

local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder

-- Update every bird every frame
RunService.Stepped:Connect(function()
	for bird, _ in pairs(birdBinder:GetAllSet()) do
		bird:Update()
	end
end)

birdBinder:Start()
warning

Do not mutate this set directly

Bind

This item only works when running on the server. Server
Binder:Bind(
instInstance--

Instance to check

) → T?--

Bound class

Binds an instance to this binder using collection service and attempts to return it if it's bound properly. See BinderUtils.promiseBoundClass() for a safe way to retrieve it.

warning

Do not assume that a bound object will be retrieved

Tag

Binder:Tag(instInstance) → ()

Tags the instance with the tag for the binder

HasTag

Binder:HasTag(instInstance) → ()

Returns true if the instance has a tag

Untag

Binder:Untag(instInstance) → ()

Untags the instance with the tag for the binder

Unbind

This item only works when running on the server. Server
Binder:Unbind(
instInstance--

Instance to unbind

) → ()

Unbinds the instance by removing the tag.

BindClient

This item only works when running on the client. Client
Binder:BindClient(
instInstance--

Instance to bind

) → T?--

Bound class (potentially)

See :Bind(). Acknowledges the risk of doing this on the client.

Using this acknowledges that we're intentionally binding on a safe client object, i.e. one without replication. If another tag is changed on this instance, this tag will be lost/changed.

UnbindClient

This item only works when running on the client. Client
Binder:UnbindClient(
instInstance--

Instance to unbind

) → ()

See Unbind(), acknowledges risk of doing this on the client.

Get

Binder:Get(
instInstance--

Instance to check

) → T?

Returns a instance of the class that is bound to the instance given.

Promise

Binder:Promise(
instInstance,--

Instance to check

cancelToken?CancelToken
) → Promise<T>

Returns a promise which will resolve when the instance is bound.

Create

Binder:Create(classNamestring | nil) → Instance

Creates a new class tagged with this binder's instance

Destroy

Binder:Destroy() → ()

Cleans up all bound classes, and disconnects all events.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new binder object.\n\n```lua\nlocal binder = Binder.new(\"Bird\", function(inst)\n\tprint(\"Wow, a new bird!\", inst)\n\n\treturn {\n\t\tDestroy = function()\n\t\t\tprint(\"Uh oh, the bird is gone!\")\n\t\tend;\n\t}\nend)\nbinder:Start()\n```",
            "params": [
                {
                    "name": "tagName",
                    "desc": "Name of the tag to bind to. This uses CollectionService's tag system",
                    "lua_type": "string"
                },
                {
                    "name": "constructor",
                    "desc": "",
                    "lua_type": "BinderContructor"
                },
                {
                    "name": "...",
                    "desc": "Variable arguments that will be passed into the constructor",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Binder<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 69,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "isBinder",
            "desc": "Retrieves whether or not the given value is a binder.",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean true or false, whether or not it is a value"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 96,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Init",
            "desc": "Initializes the Binder. Designed to be done via ServiceBag.",
            "params": [
                {
                    "name": "...",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 121,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Start",
            "desc": "Listens for new instances and connects to the GetInstanceAddedSignal() and removed signal!",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 168,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetTag",
            "desc": "Returns the tag name that the binder has.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 195,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetConstructor",
            "desc": "Returns whatever was set for the construtor. Used for meta-analysis of\nthe binder, such as extracting if parameters are allowed.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "BinderContructor"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 205,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Observe",
            "desc": "Observes the current value of the instance",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<T | nil>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 215,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "ObserveAllBrio",
            "desc": "Observes all entries in the binder",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<Brio<T>>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 235,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "ObserveBrio",
            "desc": "Observes a bound class on a given instance.",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<Brio<T>>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 272,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "ObserveInstance",
            "desc": "Fired when added, and then after removal, but before destroy!\n\n:::info\nThis is before [Rx] so it doesn't follow the same Rx pattern. See [Binder.Observe] for\nan [Rx] compatible interface.\n:::",
            "params": [
                {
                    "name": "inst",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "function"
                }
            ],
            "returns": [
                {
                    "desc": "Cleanup function",
                    "lua_type": "function"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 308,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetClassAddedSignal",
            "desc": "Returns a new signal that will fire whenever a class is bound to the binder\n\n```lua\nlocal birdBinder = Binder.new(\"Bird\", require(\"Bird\")) -- Load bird into binder\n\nbirdBinder:GetClassAddedSignal():Connect(function(bird)\n\tbird:Squack() -- Make the bird squack when it's first spawned\nend)\n\n-- Load all birds\nbirdBinder:Start()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Signal<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 343,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetClassRemovingSignal",
            "desc": "Returns a new signal that will fire whenever a class is removing from the binder.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Signal<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 358,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetClassRemovedSignal",
            "desc": "Returns a new signal that will fire whenever a class is removed from the binder.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Signal<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 374,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetAll",
            "desc": "Returns all of the classes in a new table.\n\n```lua\nlocal birdBinder = Binder.new(\"Bird\", require(\"Bird\")) -- Load bird into binder\n\n-- Update every bird every frame\nRunService.Stepped:Connect(function()\n\tfor _, bird in pairs(birdBinder:GetAll()) do\n\t\tbird:Update()\n\tend\nend)\n\nbirdBinder:Start()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{T}"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 403,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "GetAllSet",
            "desc": "Faster method to get all items in a binder\n\n```lua\nlocal birdBinder = Binder.new(\"Bird\", require(\"Bird\")) -- Load bird into binder\n\n-- Update every bird every frame\nRunService.Stepped:Connect(function()\n\tfor bird, _ in pairs(birdBinder:GetAllSet()) do\n\t\tbird:Update()\n\tend\nend)\n\nbirdBinder:Start()\n```\n\n:::warning\nDo not mutate this set directly\n:::",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ [T]: boolean }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 434,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Bind",
            "desc": "Binds an instance to this binder using collection service and attempts\nto return it if it's bound properly. See BinderUtils.promiseBoundClass() for a safe\nway to retrieve it.\n\n:::warning\nDo not assume that a bound object will be retrieved\n:::",
            "params": [
                {
                    "name": "inst",
                    "desc": "Instance to check",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "Bound class",
                    "lua_type": "T?"
                }
            ],
            "function_type": "method",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 451,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Tag",
            "desc": "Tags the instance with the tag for the binder",
            "params": [
                {
                    "name": "inst",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 466,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "HasTag",
            "desc": "Returns true if the instance has a tag",
            "params": [
                {
                    "name": "inst",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 477,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Untag",
            "desc": "Untags the instance with the tag for the binder",
            "params": [
                {
                    "name": "inst",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 488,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Unbind",
            "desc": "Unbinds the instance by removing the tag.",
            "params": [
                {
                    "name": "inst",
                    "desc": "Instance to unbind",
                    "lua_type": "Instance"
                }
            ],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Server"
            ],
            "source": {
                "line": 500,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "BindClient",
            "desc": "See :Bind(). Acknowledges the risk of doing this on the client.\n\nUsing this acknowledges that we're intentionally binding on a safe client object,\ni.e. one without replication. If another tag is changed on this instance, this tag will be lost/changed.",
            "params": [
                {
                    "name": "inst",
                    "desc": "Instance to bind",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "Bound class (potentially)",
                    "lua_type": "T?"
                }
            ],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 521,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "UnbindClient",
            "desc": "See Unbind(), acknowledges risk of doing this on the client.",
            "params": [
                {
                    "name": "inst",
                    "desc": "Instance to unbind",
                    "lua_type": "Instance"
                }
            ],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 537,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Get",
            "desc": "Returns a instance of the class that is bound to the instance given.",
            "params": [
                {
                    "name": "inst",
                    "desc": "Instance to check",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 548,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Promise",
            "desc": "Returns a promise which will resolve when the instance is bound.",
            "params": [
                {
                    "name": "inst",
                    "desc": "Instance to check",
                    "lua_type": "Instance"
                },
                {
                    "name": "cancelToken?",
                    "desc": "",
                    "lua_type": "CancelToken"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 560,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Create",
            "desc": "Creates a new class tagged with this binder's instance",
            "params": [
                {
                    "name": "className",
                    "desc": "",
                    "lua_type": "string | nil"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 571,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Cleans up all bound classes, and disconnects all events.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 677,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "BinderContructor",
            "desc": "Constructor for a binder",
            "lua_type": "(Instance, ...: any) -> T | { new: (Instance, ...: any) } | { Create(self, Instance, ...: any) }",
            "source": {
                "line": 48,
                "path": "src/binder/src/Shared/Binder.lua"
            }
        }
    ],
    "name": "Binder",
    "desc": "Bind class to Roblox Instance\n\n```lua\n-- Setup a class!\nlocal MyClass = {}\nMyClass.__index = MyClass\n\nfunction MyClass.new(robloxInstance)\n\tprint(\"New tagged instance of \", robloxInstance)\n\treturn setmetatable({}, MyClass)\nend\n\nfunction MyClass:Destroy()\n\tprint(\"Cleaning up\")\n\tsetmetatable(self, nil)\nend\n\n-- bind to every instance with tag of \"TagName\"!\nlocal binder = Binder.new(\"TagName\", MyClass)\nbinder:Start() -- listens for new instances and connects events\n```",
    "source": {
        "line": 26,
        "path": "src/binder/src/Shared/Binder.lua"
    }
}