⚠️ PLEASE NOTE: this package is currently in active development and is far from finished ⚠️

A small feature-rich Roblox-TS package for more helpful types and simpler management of instances, properties, and attributes.

Obviously inspired in some part by jQuery.

It includes an RQuery namespace for instance creation and management as well as a ton of method overrides under the $<BaseType> type.

It's this simple

npm i @rbxts/rquery

RQuery combines the already existent methods of indexing children in Roblox-TS and combines it with type overwrites to get better type prediction and autofill.

it's also NON-STRICT meaning you can still use it COMPLETELY normally without any RQuery stuff.

Better Children Indexing

RQueries override default Roblox-TS instance functions with better typed ones allowing for more type predictions and autofill.

This doesn't change anything but how you write.

type guh = $<Part & {
    baby: Decal,
    surface: SurfaceGui & {
        img: ImageLabel
    }
}>


const part = RQuery.UnreliablePath<guh>("Workspace\\*Part");


// fully predicts "baby"
part?.FindFirstChild("baby")


// fully predicts "surface" and predicts img
part?.WaitForChild("surface").FindFirstChild("img");

you can also use it to define attributes and tags

type guh = $<Part & {
    baby: Decal,
    surface: SurfaceGui & {
        img: ImageLabel
    },
    $attributes: {
        guh: 5
    },
    $tags: [
        "CoolPart"
    ]
}>

const part = RQuery.UnreliablePath<guh>("Workspace\\*Part");

part?.GetAttribute("guh");

part?.HasTag("CoolPart");

and, as said previously, works without using anything from RQuery but the types

type guh = $<Part & {
    baby: Decal,
    surface: SurfaceGui & {
        img: ImageLabel
    }
}>

const part = Workspace.WaitForChild("Part") as guh;

// also gives full types
part.WaitForChild("surface").FindFirstChild("img")

Attributes and Tags

you can overwrite the default tags and attributes like indexing children normally

// yourproject/src/rquery.d.ts

interface RQueryTags extends RQueryDefaultTags {
    guh: true
}

interface RQueryAttributes {
    burger: 1
}

using this you can also define tag attributes

// yourproject/src/rquery.d.ts
declare global {
    interface RQueryTags extends RQueryDefaultTags {
        CreatureSpawner: {
            // note: RQuery also comes with the NonstrictString type you can use
            Groups?: keyof typeof CreatureGroups | NonstrictString
            Items?: keyof typeof CreatureList | NonstrictString
        }
    }
}

type guh =  $<Part & {
    $tags: [
        "CreatureSpawner"
    ],
    $attributes: {
        AAGHH: 5
    }
}> 

const part = RQuery.UnreliablePath<guh>("Workspace\\*Part");

// fully typed tells you attributes you can get
const items = part?.GetAttribute("Items")

// also fully predicted but nonstrict
if (items === "Glup") {}

Instance Management

RQuery has a few tools for improving instance management in projects.

First: RQuery.Path and RQuery.UnreliablePath which lets you path to an instance through an extremely feature rich system including:

• shorthand names (Shared\\, Server\\, Client\\, LocalPlayer\\, Character\\, Gui\\)
• unique names (@name)
• yields (*name)
• unique name yields (*@name)
• relative (2nd argument)

RQuery.Path always gives back T so it won't tell you where it can fail good for stuff you know exists on the server

RQuery.UnreliablePath gives T | undefined and is useful on the client when you don't know if the instance exists

RQuery.Path("Workspace\\Baseplate\\Texture");
RQuery.Path("@Baseplate");
RQuery.Path("Workspace\\*Baseplate\\*Texture");
RQuery.Path("*Baseplate\\*Texture", Workspace);
RQuery.Path("*@Baseplate\\*Texture");

Second: RQuery.Instantiate which lets you create instances with complex properties, children, and attributes on the fly.

(also RQuery.Propertize)

// full type predictions for instance names, properties, children, and attributes

const part = RQuery.Instantiate("Part", {
    "Parent": Workspace,

    "Size": new Vector3(1, 1, 1),
    "Transparency": 1,

    "Attributes": {
        guh: 1,
        AGHH: "buh"
    },

    "Tags": [
        "AwesomePart"
    ],

    "Children": [
        RQuery.Instantiate("Decal", {
            "Name": "baby",
            "Texture": "rbxassetid://8088027399"
        })
    ]
})

Lastly: RQuery.New which lets you create from a class and automatically give it properties

this is mostly useful for things like params (RaycastParams, OverlapParams)

// also fully type predicted

const params = RQuery.New(RaycastParams, {
    RespectCanCollide: true,
    CollisionGroup: "PlayerPass"
})

Collaborators

Disclaimer

this package and the developers behind it are not associated with Roblox, Roblox-TS, or jQuery