@rbxts/schema

schema

A powerful tree reconciler.

usage

import { reconcileSchema } from "@rbxts/schema";

const Workspace = game.GetService("Workspace");

reconcileSchema(
	{
		// The ClassName we expect to match (doesn't use IsA)
		$className: "Folder",

		// A check to perform on this instance to determine validity
		$check: (f) => f.Name === "myFolder",

		// A callback to be called when all candidate instances are deemed invalid,
		// destroyed (but children preserved), and a new instance is instantiated.
		// The argument passed to this callback is the newly instantiated instance
		$instantiate: (f) => {
			f.Name = "myFolder";
			f.Parent = Workspace;
		},

		// A table with the valid children of this object indexed by their name
		$children: {
			isAwesome: "BoolValue", // shorthand for { $className: "BoolValue" }

			color: {
				$className: "Color3Value",

				// If we need to create a new Color3Value for this schema, set Value to white
				// If we don't need to create a new Color3Value, this won't be called
				$instantiate: (c3) => {
					c3.Value = Color3.fromRGB(255, 255, 255);
				},
			},
		},
	},
	// If `reconcileSchema` is passed `undefined` here, it will instantiate the entire tree
	// Otherwise, it will try to reconcile the above definition with the instance passed in.
	Workspace.FindFirstChild("myFolder"),
);

reconcileSchema reconciles an InstanceSchema against an Instance, while trying to preserve child instances where possible (to save instance properties). Instances are validated by their ClassName property and the optional $check callback. Child instances are made into candidates for the aforementioned check by their Name being a key in the $children table. If multiple candidates exist, this will take the first one that matches (otherwise instantiate a new object) and re-parent the children of the other candidates before continuing to the next reconcile.