///
/**
* Resolves the selector strings accepted by `Instance:QueryDescendants()` to the type of the
* instances they match, so string-literal selectors get a precise return type. The grammar is
* documented at https://create.roblox.com/docs/reference/engine/classes/Instance#QueryDescendants
*
* Only the class named in the last combinator segment affects the result, unioned across
* comma-separated selectors. `.Tag` and `#Name` carry no class information and resolve to
* `Instance`; attribute filters and pseudo-classes never change the class. Note that
* whitespace is not a combinator in this grammar (descendant matching is `>>`), so spaces
* are ignored rather than treated as separators.
*/
declare namespace Selector {
type Trim = T extends `${infer S} ` ? Trim : T extends ` ${infer S}` ? Trim : T;
type SolveHead = Head extends string
? Trim extends infer C extends keyof Instances
? Instances[C]
: Instance
: Instance;
type AddSolvedHead = [Result] extends [never]
? SolveHead
: Result | SolveHead;
type HeadBreak = ":" | "." | "#" | "[" | " ";
type ReadHead<
Head extends string | undefined = undefined,
Done extends boolean = false,
C extends string = "",
> = Done extends true
? [Head, Done]
: Head extends undefined
? Trim extends ""
? [undefined, false]
: C extends HeadBreak
? ["", true]
: [C, false]
: C extends HeadBreak
? [Head, true]
: [`${Head}${C}`, false];
type SolveChars<
S extends string,
Head extends string | undefined = undefined,
Done extends boolean = false,
Result = never,
Depth extends Array = [],
> = S extends `${infer C}${infer Rest}`
? Depth extends []
? C extends "("
? SolveChars
: C extends ","
? SolveChars, Depth>
: C extends ">"
? SolveChars
: ReadHead extends [
infer NextHead extends string | undefined,
infer NextDone extends boolean,
]
? SolveChars
: never
: C extends "("
? SolveChars
: C extends ")"
? SolveChars
: SolveChars
: AddSolvedHead;
// Nested pseudo-classes can contain selector lists, so this path tracks only top-level
// separators while keeping the subject class from the current segment.
type SlowSolve = SolveChars;
// Only the final combinator segment can determine the subject type.
type LastSegment = S extends `${string}>${infer R}` ? LastSegment : S;
type CutAt = S extends `${infer Prefix}${D}${string}` ? Prefix : S;
type LeadingClass = CutAt, ":">, ".">, "#">, " ">;
// Filters do not affect the subject class, but their values can contain selector separators.
type StripFiltersAndParens = S extends `${infer A}[${string}]${infer B}`
? StripFiltersAndParens<`${A}${B}`>
: S extends `${infer A}(${string})${infer B}`
? StripFiltersAndParens<`${A}${B}`>
: S;
type FastClause =
LeadingClass> extends infer C extends keyof Instances ? Instances[C] : Instance;
type FastSolve = S extends `${infer A},${infer B}` ? FastClause | FastSolve : FastClause;
type SolveUnquoted = S extends `${string}(${string}(${string})${string})${string}`
? SlowSolve
: FastSolve>;
type StripQuotes = S extends `${infer A}'${string}'${infer B}` ? StripQuotes<`${A}${B}`> : S;
// Attribute values are not selector syntax, even when they contain ":" or ",".
type StripValidationGroups = S extends `${infer A}'${string}'${infer B}`
? StripValidationGroups<`${A}${B}`>
: S extends `${infer A}[${string}]${infer B}`
? StripValidationGroups<`${A}${B}`>
: S;
type SupportedPseudo = "not" | "has";
type CheckPseudos = S extends `${string}:${infer R}`
? R extends `${infer Name}(${infer Rest}`
? Name extends SupportedPseudo
? CheckPseudos
: Name
: R // ':' not followed by 'name(' -> pseudo-classes require arguments
: never;
// The whole-empty selector "" is intentionally allowed.
type HasEmptyListItem = S extends `${string},${string}` ? CheckListItems : false;
type CheckListItems = S extends `${infer A},${infer B}`
? Trim extends ""
? true
: CheckListItems
: Trim extends ""
? true
: false;
type ValidateUnquoted = Q extends `${string}:${string}`
? CheckPseudos extends infer Bad
? [Bad] extends [never]
? HasEmptyListItem extends true
? `Invalid selector: empty selector in list (check for a stray or trailing comma)`
: S
: `Invalid selector: ':${Bad & string}' is not a supported pseudo-class (only ':not()' and ':has()' are allowed)`
: never
: Q extends `${string},${string}`
? HasEmptyListItem extends true
? `Invalid selector: empty selector in list (check for a stray or trailing comma)`
: S
: S;
export type ValidateSelector = string extends S
? S
: StripValidationGroups extends infer Q extends string
? ValidateUnquoted
: never;
// Quoted values are stripped before solving so most selectors can stay on the cheaper path.
export type Solve = S extends `${string}'${string}`
? SolveUnquoted>
: SolveUnquoted;
}