From d54fdc18733555577af30eb826d3386118cbfe41 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Fri, 18 Sep 2026 20:15:14 -0400 Subject: [PATCH 01/14] add hydrate --- src/instances/create.luau | 116 +----------------------------------- src/instances/hydrate.luau | 10 ++++ src/instances/types.luau | 118 +++++++++++++++++++++++++++++++++++++ 3 files changed, 131 insertions(+), 113 deletions(-) create mode 100644 src/instances/hydrate.luau create mode 100644 src/instances/types.luau diff --git a/src/instances/create.luau b/src/instances/create.luau index d5675e5..f86be61 100644 --- a/src/instances/create.luau +++ b/src/instances/create.luau @@ -1,4 +1,4 @@ -local action = require("./action") +local types = require("./types") local bind = require("./bind") type Instances = { @@ -86,59 +86,8 @@ type Instances = { Wire: Wire, } -type UnknownConnectCallback = (...any) -> () - -type Signal = RBXScriptSignal - -type function get_connect(v: type): type? - local connect = v:readproperty(types.singleton("Connect")) - - if connect and connect:is("function") then - local head = connect:parameters().head - - if not head then - return nil - end - local callback = head[2] - - if callback and callback:is("function") then - return callback - end - end - - return nil -end - -type function is_signal(v: type): type? - if v == Signal and v.tag == "extern" then - return UnknownConnectCallback - -- luau lsp types RBXScriptSignals as tables - elseif v.tag == "table" then - local connect = get_connect(v) - - if connect then - return connect - end - - -- i cba to test if this is needed or not - local metatable = v:metatable() - - if metatable then - connect = get_connect(metatable) - - if connect then - return connect - end - end - end - - return nil -end - type instance = Instance -type Action = action.Identity - type function GetInstance(class_name: type, instances: type): type if not class_name:is("singleton") then return instance @@ -147,66 +96,6 @@ type function GetInstance(class_name: type, instances: type): type return instances:readproperty(class_name) or instance end -export type function PropertiesFor(class_name: type): type - local object = GetInstance(class_name, Instances) - local head_table = {} - local args_table = { head = head_table } - local properties = types.newtable() - local current = object - local empty_table = {} - - local read_only_properties = table.freeze({ - types.singleton("RobloxLocked"), - types.singleton("ClassName"), - types.singleton("UniqueId"), - }) - - while current do - for property, value in current:properties() do - if table.find(read_only_properties, property) then - continue - end - - local value_read = value.read - local callback = is_signal(value_read) - - if callback then - properties:setproperty(property, types.optional(callback)) - elseif value_read.tag == "function" or value_read.tag == "intersection" then - continue - elseif value.write then - head_table[1] = value_read - - properties:setproperty( - property, - types.optional( - types.unionof(types.newfunction(empty_table :: any, args_table :: any), value.write) - ) - ) - end - end - - current = current:readparent() - end - - -- Functions returning a child can return an array of children, or alike functions, nested to any level - local function_returns_child = types.newfunction() - local child_only_union = types.unionof(function_returns_child, instance) - - -- TODO: Use a read only indexer when released to properly accept children which are subtypes of `Instance` - -- TODO: Nesting throws a type error, seemingly a solver bug caused whenever the keys are a union instead of direct type - -- Happens even with a union between `Instance` and `any`, but disappears when it's just `Instance` - local nested_table_or_function_or_child = types.newtable() - local nested_child_union = types.unionof(child_only_union, nested_table_or_function_or_child) - nested_table_or_function_or_child:setindexer(types.number, nested_child_union) - function_returns_child:setreturns({ nested_child_union }) - - local full_union = types.unionof(child_only_union, Action, properties) - properties:setindexer(types.number, types.optional(full_union)) - - return properties -end - local function try_create_instance(class_name: string): Instance local success, call_result = pcall(Instance.new, class_name) assert(success, call_result) @@ -214,9 +103,10 @@ local function try_create_instance(class_name: string): Instance return call_result end +--stylua: ignore local function create( class_name: ClassName | keyof | "" -): (props: PropertiesFor) -> GetInstance +): (props: types.PropertiesFor>) -> GetInstance return function(properties) return bind(try_create_instance(class_name), properties) :: any end diff --git a/src/instances/hydrate.luau b/src/instances/hydrate.luau new file mode 100644 index 0000000..80537d3 --- /dev/null +++ b/src/instances/hydrate.luau @@ -0,0 +1,10 @@ +local types = require("./types") +local bind = require("./bind") + +local function hydrate(instance: Instance): (props: types.PropertiesFor) -> Instance + return function(properties) + return bind(instance, properties) :: any + end +end + +return hydrate diff --git a/src/instances/types.luau b/src/instances/types.luau new file mode 100644 index 0000000..0356903 --- /dev/null +++ b/src/instances/types.luau @@ -0,0 +1,118 @@ +local action = require("./action") + +type UnknownConnectCallback = (...any) -> () + +type Signal = RBXScriptSignal + +type function get_connect(v: type): type? + local connect = v:readproperty(types.singleton("Connect")) + + if connect and connect:is("function") then + local head = connect:parameters().head + + if not head then + return nil + end + local callback = head[2] + + if callback and callback:is("function") then + return callback + end + end + + return nil +end + +type function is_signal(v: type): type? + if v == Signal and v.tag == "extern" then + return UnknownConnectCallback + -- luau lsp types RBXScriptSignals as tables + elseif v.tag == "table" then + local connect = get_connect(v) + + if connect then + return connect + end + + -- i cba to test if this is needed or not + local metatable = v:metatable() + + if metatable then + connect = get_connect(metatable) + + if connect then + return connect + end + end + end + + return nil +end + +type instance = Instance + +type Action = action.Identity + +export type function PropertiesFor(object: type): type + if not object:issubtypeof(instance) then + error("Cannot get properties of a non Instance type") + end + local head_table = {} + local args_table = { head = head_table } + local properties = types.newtable() + local current = object + local empty_table = {} + + local read_only_properties = table.freeze({ + types.singleton("RobloxLocked"), + types.singleton("ClassName"), + types.singleton("UniqueId"), + }) + + while current do + for property, value in current:properties() do + if table.find(read_only_properties, property) then + continue + end + + local value_read = value.read + local callback = is_signal(value_read) + + if callback then + properties:setproperty(property, types.optional(callback)) + elseif value_read.tag == "function" or value_read.tag == "intersection" then + continue + elseif value.write then + head_table[1] = value_read + + properties:setproperty( + property, + types.optional( + types.unionof(types.newfunction(empty_table :: any, args_table :: any), value.write) + ) + ) + end + end + + current = current:readparent() + end + + -- Functions returning a child can return an array of children, or alike functions, nested to any level + local function_returns_child = types.newfunction() + local child_only_union = types.unionof(function_returns_child, instance) + + -- TODO: Use a read only indexer when released to properly accept children which are subtypes of `Instance` + -- TODO: Nesting throws a type error, seemingly a solver bug caused whenever the keys are a union instead of direct type + -- Happens even with a union between `Instance` and `any`, but disappears when it's just `Instance` + local nested_table_or_function_or_child = types.newtable() + local nested_child_union = types.unionof(child_only_union, nested_table_or_function_or_child) + nested_table_or_function_or_child:setindexer(types.number, nested_child_union) + function_returns_child:setreturns({ nested_child_union }) + + local full_union = types.unionof(child_only_union, Action, properties) + properties:setindexer(types.number, types.optional(full_union)) + + return properties +end + +return nil From a50320eff2755128bd7fcb1c8c1f7a1677490957 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Fri, 18 Sep 2026 20:46:34 -0400 Subject: [PATCH 02/14] oops i forgot to export hydrate, and fix the export for PropertiesFor --- src/init.luau | 5 +- src/instances/create.luau | 99 +---------------------------------- src/instances/types.luau | 106 ++++++++++++++++++++++++++++++++++++-- 3 files changed, 107 insertions(+), 103 deletions(-) diff --git a/src/init.luau b/src/init.luau index 34108a4..b9de033 100644 --- a/src/init.luau +++ b/src/init.luau @@ -25,11 +25,13 @@ local switch_delay = require("@self/utils/switch_delay") local tags = require("@self/utils/tags") local types = require("@self/reactive/types") local untrack = require("@self/reactive/untrack") +local hydrate = require("@self/instances/hydrate") +local instance_types = require("@self/instances/types") export type UsedAs = types.UsedAs export type Source = types.Source export type Action = action.Identity -export type PropertiesFor = create.PropertiesFor +export type PropertiesFor = instance_types.PropertiesFor local scheduler_thread: thread? = nil @@ -59,6 +61,7 @@ end local fluid = {} +fluid.hydrate = hydrate fluid.create = create fluid.mount = mount fluid.tags = tags diff --git a/src/instances/create.luau b/src/instances/create.luau index f86be61..0613f1b 100644 --- a/src/instances/create.luau +++ b/src/instances/create.luau @@ -1,101 +1,6 @@ local types = require("./types") local bind = require("./bind") -type Instances = { - PyramidHandleAdornment: PyramidHandleAdornment, - AudioChannelSplitter: AudioChannelSplitter, - AudioPitchShifter: AudioPitchShifter, - AudioDeviceOutput: AudioDeviceOutput, - AudioChannelMixer: AudioChannelMixer, - AudioTextToSpeech: AudioTextToSpeech, - AudioDeviceInput: AudioDeviceInput, - AudioDistortion: AudioDistortion, - AudioCompressor: AudioCompressor, - AudioEqualizer: AudioEqualizer, - AudioAnalyzer: AudioAnalyzer, - AudioListener: AudioListener, - AudioRecorder: AudioRecorder, - AudioLimiter: AudioLimiter, - AudioFlanger: AudioFlanger, - AudioEmitter: AudioEmitter, - AudioPlayer: AudioPlayer, - AudioReverb: AudioReverb, - AudioFilter: AudioFilter, - ArcHandles: ArcHandles, - AudioFader: AudioFader, - AudioEcho: AudioEcho, - AdGui: AdGui, - BoxHandleAdornment: BoxHandleAdornment, - BillboardGui: BillboardGui, - BlurEffect: BlurEffect, - CylinderHandleAdornment: CylinderHandleAdornment, - ConeHandleAdornment: ConeHandleAdornment, - CanvasGroup: CanvasGroup, - Camera: Camera, - DialogChoice: DialogChoice, - DragDetector: DragDetector, - Dialog: Dialog, - Folder: Folder, - Frame: Frame, - Highlight: Highlight, - Handles: Handles, - ImageHandLeAdornment: ImageHandleAdornment, - ImageButton: ImageButton, - ImageLabel: ImageLabel, - LineHandleAdornment: LineHandleAdornment, - ProximityPrompt: ProximityPrompt, - Path2D: Path2D, - Part: Part, - SphereHandLeAdornment: SphereHandleAdornment, - SelectionSphere: SelectionSphere, - ScrollingFrame: ScrollingFrame, - SelectionBox: SelectionBox, - StyleDerive: StyleDerive, - StyleQuery: StyleQuery, - SurfaceGui: SurfaceGui, - StyleSheet: StyleSheet, - SoundGroup: SoundGroup, - StyleLink: StyleLink, - ScreenGui: ScreenGui, - StyleBase: StyleBase, - StyleRule: StyleRule, - Sound: Sound, - TextButton: TextButton, - TextLabel: TextLabel, - TextBox: TextBox, - UIAspectRatioConstraint: UIAspectRatioConstraint, - UITextSizeConstraint: UITextSizeConstraint, - UISizeConstraint: UISizeConstraint, - UIDragDetector: UIDragDetector, - UITableLayout: UITableLayout, - UIPageLayout: UIPageLayout, - UIGridLayout: UIGridLayout, - UIListLayout: UIListLayout, - UIGradient: UIGradient, - UIFlexItem: UIFlexItem, - UIPadding: UIPadding, - UIStroke: UIStroke, - UICorner: UICorner, - UIShadow: UIShadow, - UIScale: UIScale, - ViewportFrame: ViewportFrame, - VideoDisplay: VideoDisplay, - VideoFrame: VideoFrame, - WireframeHandleAdornment: WireframeHandleAdornment, - WorldModel: WorldModel, - Wire: Wire, -} - -type instance = Instance - -type function GetInstance(class_name: type, instances: type): type - if not class_name:is("singleton") then - return instance - end - - return instances:readproperty(class_name) or instance -end - local function try_create_instance(class_name: string): Instance local success, call_result = pcall(Instance.new, class_name) assert(success, call_result) @@ -105,8 +10,8 @@ end --stylua: ignore local function create( - class_name: ClassName | keyof | "" -): (props: types.PropertiesFor>) -> GetInstance + class_name: ClassName | keyof | "" +): (props: types.PropertiesFor) -> types.GetInstance return function(properties) return bind(try_create_instance(class_name), properties) :: any end diff --git a/src/instances/types.luau b/src/instances/types.luau index 0356903..61e5916 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -1,5 +1,100 @@ local action = require("./action") +export type Instances = { + PyramidHandleAdornment: PyramidHandleAdornment, + AudioChannelSplitter: AudioChannelSplitter, + AudioPitchShifter: AudioPitchShifter, + AudioDeviceOutput: AudioDeviceOutput, + AudioChannelMixer: AudioChannelMixer, + AudioTextToSpeech: AudioTextToSpeech, + AudioDeviceInput: AudioDeviceInput, + AudioDistortion: AudioDistortion, + AudioCompressor: AudioCompressor, + AudioEqualizer: AudioEqualizer, + AudioAnalyzer: AudioAnalyzer, + AudioListener: AudioListener, + AudioRecorder: AudioRecorder, + AudioLimiter: AudioLimiter, + AudioFlanger: AudioFlanger, + AudioEmitter: AudioEmitter, + AudioPlayer: AudioPlayer, + AudioReverb: AudioReverb, + AudioFilter: AudioFilter, + ArcHandles: ArcHandles, + AudioFader: AudioFader, + AudioEcho: AudioEcho, + AdGui: AdGui, + BoxHandleAdornment: BoxHandleAdornment, + BillboardGui: BillboardGui, + BlurEffect: BlurEffect, + CylinderHandleAdornment: CylinderHandleAdornment, + ConeHandleAdornment: ConeHandleAdornment, + CanvasGroup: CanvasGroup, + Camera: Camera, + DialogChoice: DialogChoice, + DragDetector: DragDetector, + Dialog: Dialog, + Folder: Folder, + Frame: Frame, + Highlight: Highlight, + Handles: Handles, + ImageHandLeAdornment: ImageHandleAdornment, + ImageButton: ImageButton, + ImageLabel: ImageLabel, + LineHandleAdornment: LineHandleAdornment, + ProximityPrompt: ProximityPrompt, + Path2D: Path2D, + Part: Part, + SphereHandLeAdornment: SphereHandleAdornment, + SelectionSphere: SelectionSphere, + ScrollingFrame: ScrollingFrame, + SelectionBox: SelectionBox, + StyleDerive: StyleDerive, + StyleQuery: StyleQuery, + SurfaceGui: SurfaceGui, + StyleSheet: StyleSheet, + SoundGroup: SoundGroup, + StyleLink: StyleLink, + ScreenGui: ScreenGui, + StyleBase: StyleBase, + StyleRule: StyleRule, + Sound: Sound, + TextButton: TextButton, + TextLabel: TextLabel, + TextBox: TextBox, + UIAspectRatioConstraint: UIAspectRatioConstraint, + UITextSizeConstraint: UITextSizeConstraint, + UISizeConstraint: UISizeConstraint, + UIDragDetector: UIDragDetector, + UITableLayout: UITableLayout, + UIPageLayout: UIPageLayout, + UIGridLayout: UIGridLayout, + UIListLayout: UIListLayout, + UIGradient: UIGradient, + UIFlexItem: UIFlexItem, + UIPadding: UIPadding, + UIStroke: UIStroke, + UICorner: UICorner, + UIShadow: UIShadow, + UIScale: UIScale, + ViewportFrame: ViewportFrame, + VideoDisplay: VideoDisplay, + VideoFrame: VideoFrame, + WireframeHandleAdornment: WireframeHandleAdornment, + WorldModel: WorldModel, + Wire: Wire, +} + +type instance = Instance + +export type function GetInstance(class_name: type, instances: type): type + if not class_name:is("singleton") then + return instance + end + + return instances:readproperty(class_name) or instance +end + type UnknownConnectCallback = (...any) -> () type Signal = RBXScriptSignal @@ -49,18 +144,19 @@ type function is_signal(v: type): type? return nil end -type instance = Instance - type Action = action.Identity export type function PropertiesFor(object: type): type - if not object:issubtypeof(instance) then + if object.tag == "singleton" then + object = GetInstance(object, Instances) + elseif not object:issubtypeof(instance) then error("Cannot get properties of a non Instance type") end + local head_table = {} local args_table = { head = head_table } local properties = types.newtable() - local current = object + local current = object :: type local empty_table = {} local read_only_properties = table.freeze({ @@ -75,7 +171,7 @@ export type function PropertiesFor(object: type): type continue end - local value_read = value.read + local value_read = value.read :: type local callback = is_signal(value_read) if callback then From d7f90b90003a7afbb10b73e74dbb421f2e8ede63 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Fri, 18 Sep 2026 20:49:50 -0400 Subject: [PATCH 03/14] format (i hate stylua mandating that requires need to be ascending instead of descending) --- src/init.luau | 4 ++-- src/instances/create.luau | 2 +- src/instances/hydrate.luau | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/init.luau b/src/init.luau index b9de033..33d12ee 100644 --- a/src/init.luau +++ b/src/init.luau @@ -10,6 +10,8 @@ local effect = require("@self/reactive/effect") local for_keys = require("@self/instances/for_keys") local for_values = require("@self/instances/for_values") local graph = require("@self/reactive/graph") +local hydrate = require("@self/instances/hydrate") +local instance_types = require("@self/instances/types") local interval = require("@self/utils/interval") local lerp = require("@self/anim/lerp") local mount = require("@self/instances/mount") @@ -25,8 +27,6 @@ local switch_delay = require("@self/utils/switch_delay") local tags = require("@self/utils/tags") local types = require("@self/reactive/types") local untrack = require("@self/reactive/untrack") -local hydrate = require("@self/instances/hydrate") -local instance_types = require("@self/instances/types") export type UsedAs = types.UsedAs export type Source = types.Source diff --git a/src/instances/create.luau b/src/instances/create.luau index 0613f1b..c7c3e55 100644 --- a/src/instances/create.luau +++ b/src/instances/create.luau @@ -1,5 +1,5 @@ -local types = require("./types") local bind = require("./bind") +local types = require("./types") local function try_create_instance(class_name: string): Instance local success, call_result = pcall(Instance.new, class_name) diff --git a/src/instances/hydrate.luau b/src/instances/hydrate.luau index 80537d3..2ba0acf 100644 --- a/src/instances/hydrate.luau +++ b/src/instances/hydrate.luau @@ -1,5 +1,5 @@ -local types = require("./types") local bind = require("./bind") +local types = require("./types") local function hydrate(instance: Instance): (props: types.PropertiesFor) -> Instance return function(properties) From 97c78a78916df746ff4be23351f4cfcf1998d92c Mon Sep 17 00:00:00 2001 From: nnullcolumn <264514568+nnullcolumn@users.noreply.github.com> Date: Wed, 23 Sep 2026 01:57:22 -0500 Subject: [PATCH 04/14] fix optional value source type errs (#65) --- src/reactive/types.luau | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/reactive/types.luau b/src/reactive/types.luau index 2ef0b0e..3984626 100644 --- a/src/reactive/types.luau +++ b/src/reactive/types.luau @@ -3,7 +3,9 @@ export type Callable = (value: T) -> () export type Effect = (value: T) -> T -export type Source = ((T) -> T) & Readable +-- somewhat misleading but will never produce invalid calls and has +-- less false positive type errors +export type Source = (...T) -> T export type UsedAs = T | Readable From 5b7f4574cbeaa5e9d558cd45ae457e92085e9710 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Wed, 23 Sep 2026 22:38:45 -0400 Subject: [PATCH 05/14] update instances list --- src/instances/types.luau | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/instances/types.luau b/src/instances/types.luau index 61e5916..953db92 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -39,10 +39,12 @@ export type Instances = { Highlight: Highlight, Handles: Handles, ImageHandLeAdornment: ImageHandleAdornment, + InputActionLabel: InputActionLabel, ImageButton: ImageButton, ImageLabel: ImageLabel, LineHandleAdornment: LineHandleAdornment, ProximityPrompt: ProximityPrompt, + Path3D: Path3D, Path2D: Path2D, Part: Part, SphereHandLeAdornment: SphereHandleAdornment, @@ -77,6 +79,7 @@ export type Instances = { UICorner: UICorner, UIShadow: UIShadow, UIScale: UIScale, + ViewportCamera: ViewportCamera, ViewportFrame: ViewportFrame, VideoDisplay: VideoDisplay, VideoFrame: VideoFrame, From f05a71c468670bfc63d6bf33fec288e6848791e2 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Sun, 27 Sep 2026 13:00:14 -0400 Subject: [PATCH 06/14] add hydrate to docs --- docs/guides/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 476bd10..b8633e0 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -19,6 +19,7 @@ fluid = "ffrostfall/fluid@" # API overview - fluid.create("Frame")({ property = value }) +- fluid.hydrate(Instance.new("Frame"))({ property = value }) - fluid.source() - fluid.async() - fluid.derive() From 4a0f4d531d441f51027e4776bfc49f229e988bda Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Sun, 27 Sep 2026 14:16:19 -0400 Subject: [PATCH 07/14] * update bind to have better types * remove hydrate (its just bind) * export is_signal from the instances types.luau (so it can be used in my style sheet wrapper thingy) * make PropertiesFor accept intsersection types, mainly for use with fake generic constraints * make the properties table start off as an actual table, so each property set doesnt have to go through methods * use readindexers instead of indexers on the table types created by PropertiesFor * remove empty table from PropertiesFor * add a type function for getting an array of read only property indexers (this is so my style sheets wrapper branch doesnt have to duplicate the table) * rename first argument of bind to instance because inst is weird --- docs/guides/getting-started.md | 1 - src/init.luau | 4 +-- src/instances/bind.luau | 25 ++++++++--------- src/instances/hydrate.luau | 10 ------- src/instances/types.luau | 49 ++++++++++++++++++++-------------- 5 files changed, 43 insertions(+), 46 deletions(-) delete mode 100644 src/instances/hydrate.luau diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index b8633e0..476bd10 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -19,7 +19,6 @@ fluid = "ffrostfall/fluid@" # API overview - fluid.create("Frame")({ property = value }) -- fluid.hydrate(Instance.new("Frame"))({ property = value }) - fluid.source() - fluid.async() - fluid.derive() diff --git a/src/init.luau b/src/init.luau index 33d12ee..40eb0a1 100644 --- a/src/init.luau +++ b/src/init.luau @@ -10,7 +10,6 @@ local effect = require("@self/reactive/effect") local for_keys = require("@self/instances/for_keys") local for_values = require("@self/instances/for_values") local graph = require("@self/reactive/graph") -local hydrate = require("@self/instances/hydrate") local instance_types = require("@self/instances/types") local interval = require("@self/utils/interval") local lerp = require("@self/anim/lerp") @@ -31,7 +30,7 @@ local untrack = require("@self/reactive/untrack") export type UsedAs = types.UsedAs export type Source = types.Source export type Action = action.Identity -export type PropertiesFor = instance_types.PropertiesFor +export type PropertiesFor = instance_types.PropertiesFor local scheduler_thread: thread? = nil @@ -61,7 +60,6 @@ end local fluid = {} -fluid.hydrate = hydrate fluid.create = create fluid.mount = mount fluid.tags = tags diff --git a/src/instances/bind.luau b/src/instances/bind.luau index f052a1d..5f480dd 100644 --- a/src/instances/bind.luau +++ b/src/instances/bind.luau @@ -1,6 +1,7 @@ local action = require("./action") local graph = require("../reactive/graph") -local types = require("../reactive/types") +local reactive_types = require("../reactive/types") +local instance_types = require("./types") local function set_property(inst: Instance, property: string, value: any) (inst :: any)[property] = value @@ -10,7 +11,7 @@ local function get_property(inst: Instance, property: string): any return (inst :: any)[property] end -local function bind_property(inst: Instance, property: string, value: types.Readable) +local function bind_property(inst: Instance, property: string, value: reactive_types.Readable) local property_node = graph.create_reactive_node(graph.assert_stable_parent(), function() set_property(inst, property, value()) return nil @@ -101,17 +102,17 @@ local function bind_reactive_child(inst: Instance, func: () -> Result) graph.evaluate_node(property_node) end -local function bind(inst: Instance, props: { [unknown & number]: unknown }) - for key: any, value: any in props do +local function bind(instance: I & Instance, props: instance_types.PropertiesFor): I + for key, value in props :: any do local key_type, value_type = type(key), typeof(value) if key_type == "string" then - local property_value = get_property(inst, key) + local property_value = get_property(instance, key) if typeof(property_value) ~= "RBXScriptSignal" then if value_type == "function" then - bind_property(inst, key, value) + bind_property(instance, key, value) else - set_property(inst, key, value) + set_property(instance, key, value) end elseif value_type == "function" then local connection = property_value:Connect(value) @@ -122,19 +123,19 @@ local function bind(inst: Instance, props: { [unknown & number]: unknown }) end else if value_type == "Instance" then - value.Parent = inst + value.Parent = instance elseif value_type == "table" then if value.__ACTION_SYMBOL == action.symbol then - value.callback(inst) + value.callback(instance) else - bind(inst, value) + bind(instance, value) end elseif value_type == "function" then - bind_reactive_child(inst, value) + bind_reactive_child(instance, value) end end end - return inst + return instance end return bind diff --git a/src/instances/hydrate.luau b/src/instances/hydrate.luau deleted file mode 100644 index 2ba0acf..0000000 --- a/src/instances/hydrate.luau +++ /dev/null @@ -1,10 +0,0 @@ -local bind = require("./bind") -local types = require("./types") - -local function hydrate(instance: Instance): (props: types.PropertiesFor) -> Instance - return function(properties) - return bind(instance, properties) :: any - end -end - -return hydrate diff --git a/src/instances/types.luau b/src/instances/types.luau index 953db92..35cf998 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -121,7 +121,7 @@ type function get_connect(v: type): type? return nil end -type function is_signal(v: type): type? +export type function is_signal(v: type): type? if v == Signal and v.tag == "extern" then return UnknownConnectCallback -- luau lsp types RBXScriptSignals as tables @@ -149,24 +149,37 @@ end type Action = action.Identity +export type function get_read_only_instance_properties(): { type } + return table.freeze({ + types.singleton("RobloxLocked"), + types.singleton("ClassName"), + types.singleton("UniqueId"), + }) +end + export type function PropertiesFor(object: type): type + -- support for fake generic constraints ie types like T & Instance + if object.tag == "intersection" then + local components = object:components() + + if #components == 2 then + object = components[1] + else + error("cannot provide an intersection type with more than 2 components to PropertiesFor") + end + end + if object.tag == "singleton" then object = GetInstance(object, Instances) elseif not object:issubtypeof(instance) then error("Cannot get properties of a non Instance type") end + local read_only_properties = get_read_only_instance_properties() local head_table = {} local args_table = { head = head_table } - local properties = types.newtable() + local properties = {} :: { [type]: type } local current = object :: type - local empty_table = {} - - local read_only_properties = table.freeze({ - types.singleton("RobloxLocked"), - types.singleton("ClassName"), - types.singleton("UniqueId"), - }) while current do for property, value in current:properties() do @@ -178,17 +191,14 @@ export type function PropertiesFor(object: type): type local callback = is_signal(value_read) if callback then - properties:setproperty(property, types.optional(callback)) + properties[property] = types.optional(callback) elseif value_read.tag == "function" or value_read.tag == "intersection" then continue elseif value.write then head_table[1] = value_read - properties:setproperty( - property, - types.optional( - types.unionof(types.newfunction(empty_table :: any, args_table :: any), value.write) - ) + properties[property] = types.optional( + types.unionof(types.newfunction(nil, args_table :: any), value.write) ) end end @@ -196,20 +206,19 @@ export type function PropertiesFor(object: type): type current = current:readparent() end + properties = types.newtable(properties) + -- Functions returning a child can return an array of children, or alike functions, nested to any level local function_returns_child = types.newfunction() local child_only_union = types.unionof(function_returns_child, instance) - -- TODO: Use a read only indexer when released to properly accept children which are subtypes of `Instance` - -- TODO: Nesting throws a type error, seemingly a solver bug caused whenever the keys are a union instead of direct type - -- Happens even with a union between `Instance` and `any`, but disappears when it's just `Instance` local nested_table_or_function_or_child = types.newtable() local nested_child_union = types.unionof(child_only_union, nested_table_or_function_or_child) - nested_table_or_function_or_child:setindexer(types.number, nested_child_union) + nested_table_or_function_or_child:setreadindexer(types.number, nested_child_union) function_returns_child:setreturns({ nested_child_union }) local full_union = types.unionof(child_only_union, Action, properties) - properties:setindexer(types.number, types.optional(full_union)) + properties:setreadindexer(types.number, types.optional(full_union)) return properties end From 6a9d0dc770f248465f495a0432c0878dd92284a1 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Sun, 27 Sep 2026 14:18:49 -0400 Subject: [PATCH 08/14] formatting --- src/instances/bind.luau | 4 ++-- src/instances/types.luau | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/instances/bind.luau b/src/instances/bind.luau index 5f480dd..a81cb5b 100644 --- a/src/instances/bind.luau +++ b/src/instances/bind.luau @@ -1,7 +1,7 @@ -local action = require("./action") -local graph = require("../reactive/graph") local reactive_types = require("../reactive/types") +local graph = require("../reactive/graph") local instance_types = require("./types") +local action = require("./action") local function set_property(inst: Instance, property: string, value: any) (inst :: any)[property] = value diff --git a/src/instances/types.luau b/src/instances/types.luau index 35cf998..30b5836 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -197,6 +197,7 @@ export type function PropertiesFor(object: type): type elseif value.write then head_table[1] = value_read + --stylua: ignore properties[property] = types.optional( types.unionof(types.newfunction(nil, args_table :: any), value.write) ) From 5b5c01e3d7ff4958185565bbb72be0e6514335c2 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Sun, 27 Sep 2026 14:20:05 -0400 Subject: [PATCH 09/14] appease stylua having the worst require formatting style --- src/instances/bind.luau | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/instances/bind.luau b/src/instances/bind.luau index a81cb5b..c816193 100644 --- a/src/instances/bind.luau +++ b/src/instances/bind.luau @@ -1,7 +1,7 @@ -local reactive_types = require("../reactive/types") +local action = require("./action") local graph = require("../reactive/graph") local instance_types = require("./types") -local action = require("./action") +local reactive_types = require("../reactive/types") local function set_property(inst: Instance, property: string, value: any) (inst :: any)[property] = value From 8979bdf89d0540ba3ba7b83b39753e9674301292 Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Sun, 27 Sep 2026 17:55:50 -0400 Subject: [PATCH 10/14] oops --- src/instances/types.luau | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/instances/types.luau b/src/instances/types.luau index 30b5836..c667625 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -209,17 +209,18 @@ export type function PropertiesFor(object: type): type properties = types.newtable(properties) + -- TODO: Use a read only indexer when released to properly accept children which are subtypes of `Instance` -- Functions returning a child can return an array of children, or alike functions, nested to any level local function_returns_child = types.newfunction() local child_only_union = types.unionof(function_returns_child, instance) local nested_table_or_function_or_child = types.newtable() local nested_child_union = types.unionof(child_only_union, nested_table_or_function_or_child) - nested_table_or_function_or_child:setreadindexer(types.number, nested_child_union) + nested_table_or_function_or_child:setindexer(types.number, nested_child_union) function_returns_child:setreturns({ nested_child_union }) local full_union = types.unionof(child_only_union, Action, properties) - properties:setreadindexer(types.number, types.optional(full_union)) + properties:setindexer(types.number, types.optional(full_union)) return properties end From b73d2839d0b27046ec031fdb8967692fd55cbcfe Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 13 Oct 2026 19:19:27 -0400 Subject: [PATCH 11/14] * publicly expose GetInstance * allow for passing `any` & `unknown` to GetInstance & PropertiesFor * actually get the type of :Connect() for RBXScriptSignals using an extern type, as it turns out its possible to do in roblox * allow for providing default properties to PropertiesFor<> via intersections `Frame & { Name: "Divider" }` as a nice alternative to fluid having default properties at runtime --- src/init.luau | 3 +- src/instances/types.luau | 205 ++++++++++++++++++++++++--------------- 2 files changed, 130 insertions(+), 78 deletions(-) diff --git a/src/init.luau b/src/init.luau index 40eb0a1..e2dfa9f 100644 --- a/src/init.luau +++ b/src/init.luau @@ -30,7 +30,8 @@ local untrack = require("@self/reactive/untrack") export type UsedAs = types.UsedAs export type Source = types.Source export type Action = action.Identity -export type PropertiesFor = instance_types.PropertiesFor +export type PropertiesFor = instance_types.PropertiesFor +export type GetInstance = instance_types.GetInstance local scheduler_thread: thread? = nil diff --git a/src/instances/types.luau b/src/instances/types.luau index c667625..f0e2f1d 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -88,67 +88,30 @@ export type Instances = { Wire: Wire, } +type Action = action.Identity + type instance = Instance -export type function GetInstance(class_name: type, instances: type): type - if not class_name:is("singleton") then - return instance +export type function get_instance(type_instance: type, instances: type, _instance: type): type + if type_instance.tag == "singleton" then + return instances:readproperty(type_instance) or _instance + -- this is here so passing PropertiesFor a type like any because of a type solver issue, + -- or passing it any or unknown in a prototype class will still work + elseif type_instance == types.unknown or type_instance == types.any then + return _instance + elseif type_instance:issubtypeof(_instance) then + return type_instance end - return instances:readproperty(class_name) or instance + error( + `Can't convert type '{type_instance}' into an Instance type because it's not 'unknown', 'any', a ClassName string singleton, or a subtype of '{_instance}'` + ) end -type UnknownConnectCallback = (...any) -> () - -type Signal = RBXScriptSignal - -type function get_connect(v: type): type? - local connect = v:readproperty(types.singleton("Connect")) - - if connect and connect:is("function") then - local head = connect:parameters().head - - if not head then - return nil - end - local callback = head[2] - - if callback and callback:is("function") then - return callback - end - end - - return nil +export type function GetInstance(type_instance: type): type + return get_instance(type_instance, Instances, instance) end -export type function is_signal(v: type): type? - if v == Signal and v.tag == "extern" then - return UnknownConnectCallback - -- luau lsp types RBXScriptSignals as tables - elseif v.tag == "table" then - local connect = get_connect(v) - - if connect then - return connect - end - - -- i cba to test if this is needed or not - local metatable = v:metatable() - - if metatable then - connect = get_connect(metatable) - - if connect then - return connect - end - end - end - - return nil -end - -type Action = action.Identity - export type function get_read_only_instance_properties(): { type } return table.freeze({ types.singleton("RobloxLocked"), @@ -157,29 +120,81 @@ export type function get_read_only_instance_properties(): { type } }) end -export type function PropertiesFor(object: type): type - -- support for fake generic constraints ie types like T & Instance - if object.tag == "intersection" then - local components = object:components() +export type function PropertiesFor(type_instance: type): type + -- uses the string values of the property name instead of the type instances + -- as luau currently doesn't have singleton type userdatas setup to be the same if their value is the same + local default_properties = {} :: { [string]: type } + local type_tag = type_instance.tag + + -- dealing with intersections like this to support "generic constraints" ie T & { Name: "Head" } + -- and also for providing default properties to an instance ie Frame & { Name: "Divider" }, + -- or nested default properties ie (Frame & { Name: "Divider" }) & (Frame & { Parent: ScreenGui }) + if type_tag == "intersection" then + local components = type_instance:components() + local total_components = #components + local class: type? + + while total_components > 0 do + local component = components[total_components] + total_components -= 1 + + local component_tag = component.tag + + if component_tag == "intersection" then + for _, inner_component in component:components() do + total_components += 1 + components[total_components] = inner_component + end + continue + elseif component_tag == "table" then + for property, value in component:properties() do + local value_type = value.write or value.read + + if value_type then + local key = property:value() :: string + local default_value = default_properties[key] + + default_properties[key] = if default_value + then types.unionof(default_value, value_type) + else value_type + end + end + continue + end + + -- doing this to support generics in the cases of like prototype metatables + -- local prototype = {} :: ClassPrototype + if component == types.any or component == types.unknown then + component = instance + elseif not component:issubtypeof(instance) then + --stylua: ignore + error(`Expected component to be a properties table or '{instance}', but got '{component}'`) + end - if #components == 2 then - object = components[1] - else - error("cannot provide an intersection type with more than 2 components to PropertiesFor") + if component == instance or not class then + class = component + elseif class ~= instance then + -- the component's class could be any class, so we're getting their closest common ancestor as the class to get properties for + -- to avoid issues with properties being allowed that don't exist on the instance that is having its properties set + while not component:issubtypeof(class) do + class = class:readparent() or instance + end + end end - end - if object.tag == "singleton" then - object = GetInstance(object, Instances) - elseif not object:issubtypeof(instance) then - error("Cannot get properties of a non Instance type") + if not class then + error("No class found in the intersection provided") + end + type_instance = class + else + type_instance = get_instance(type_instance, Instances, instance) end local read_only_properties = get_read_only_instance_properties() local head_table = {} local args_table = { head = head_table } local properties = {} :: { [type]: type } - local current = object :: type + local current = type_instance :: type while current do for property, value in current:properties() do @@ -187,21 +202,57 @@ export type function PropertiesFor(object: type): type continue end - local value_read = value.read :: type - local callback = is_signal(value_read) + local write_value = value.write :: type + local read_value = value.read :: type + -- doing it like this because roblox may actually make their types more accurate, + -- as callbacks on instances can't be read to get the callback + local value_tag = ((read_value or write_value) :: type).tag - if callback then - properties[property] = types.optional(callback) - elseif value_read.tag == "function" or value_read.tag == "intersection" then + -- TODO: special case functions when instance methods get marked as read only, as instances can have callback properties + -- such as RemoteFunction.OnServerInvoke + if value_tag == "function" or value_tag == "intersection" then continue - elseif value.write then - head_table[1] = value_read + end + + local connect: type + + if value_tag == "extern" then + -- iterating :properties() here because as of writing doing the following doesn't work + -- because type userdatas aren't the same even if they have the same value and also because extern type userdatas don't have :readproperty() + -- connect = t:properties()[types.singleton("Connect")].read + for key, value in read_value:properties() do + if key:value() == "Connect" then + connect = value.read or value.write :: any + break + end + end + -- luau lsp types RBXScriptSignals as tables + elseif value_tag == "table" then + connect = read_value:readproperty(types.singleton("Connect")) :: any + end + + local property_value: type + + if connect then + property_value = types.optional(connect:parameters().head[2]) + elseif write_value then + head_table[1] = read_value --stylua: ignore - properties[property] = types.optional( - types.unionof(types.newfunction(nil, args_table :: any), value.write) - ) + property_value = types.optional(types.unionof(types.newfunction(nil, args_table :: any), write_value)) + local property_name = property:value() :: string + local default_value = default_properties[property_name] + + if default_value then + if not default_value:issubtypeof(write_value) then + --stylua: ignore + error(`Expected default value provided for property '{property_name}' to be '{write_value}', but got '{default_value}' via one of the tables in the intersection provided`) + end + property_value = types.unionof(property_value, default_value) + end end + + properties[property] = property_value end current = current:readparent() From c4fc0bce22208b5f604dfc473e3b86b7c5a64d4a Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 13 Oct 2026 19:26:05 -0400 Subject: [PATCH 12/14] comment fix --- src/instances/types.luau | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/instances/types.luau b/src/instances/types.luau index f0e2f1d..a5bbcac 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -205,7 +205,7 @@ export type function PropertiesFor(type_instance: type): type local write_value = value.write :: type local read_value = value.read :: type -- doing it like this because roblox may actually make their types more accurate, - -- as callbacks on instances can't be read to get the callback + -- as callbacks on instances can't be read to get the callback, but they're typed as if they can be read local value_tag = ((read_value or write_value) :: type).tag -- TODO: special case functions when instance methods get marked as read only, as instances can have callback properties From 1b3df95a1eae0616c2211f7170e7692f2766b55f Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 13 Oct 2026 19:34:03 -0400 Subject: [PATCH 13/14] add ParticleEmitter2D early --- src/instances/types.luau | 1 + 1 file changed, 1 insertion(+) diff --git a/src/instances/types.luau b/src/instances/types.luau index a5bbcac..72d5453 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -2,6 +2,7 @@ local action = require("./action") export type Instances = { PyramidHandleAdornment: PyramidHandleAdornment, + ParticleEmitter2D: ParticleEmitter2D, AudioChannelSplitter: AudioChannelSplitter, AudioPitchShifter: AudioPitchShifter, AudioDeviceOutput: AudioDeviceOutput, From 01c753118130ab3b08ba6ccdb91e53dbe46aeeee Mon Sep 17 00:00:00 2001 From: gaymeowing <62822174+gaymeowing@users.noreply.github.com> Date: Tue, 13 Oct 2026 19:39:40 -0400 Subject: [PATCH 14/14] add UIBlur & ParticleEmitter to the Instances table --- src/instances/types.luau | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/instances/types.luau b/src/instances/types.luau index 72d5453..5e42134 100644 --- a/src/instances/types.luau +++ b/src/instances/types.luau @@ -3,6 +3,7 @@ local action = require("./action") export type Instances = { PyramidHandleAdornment: PyramidHandleAdornment, ParticleEmitter2D: ParticleEmitter2D, + ParticleEmitter: ParticleEmitter, AudioChannelSplitter: AudioChannelSplitter, AudioPitchShifter: AudioPitchShifter, AudioDeviceOutput: AudioDeviceOutput, @@ -80,6 +81,7 @@ export type Instances = { UICorner: UICorner, UIShadow: UIShadow, UIScale: UIScale, + UIBlur: UIBlur, ViewportCamera: ViewportCamera, ViewportFrame: ViewportFrame, VideoDisplay: VideoDisplay,