roblox-ts / types

TypeScript typings for the Roblox platform. Partially handwritten and partially automatically generated.

roblox-ts

A TypeScript-to-Luau Compiler for Roblox

 

Introduction

roblox-ts is an attempt to bridge the abilities of TypeScript to work in a Roblox environment. We break down your code into an abstract syntax tree and emit functionally similar structures in Luau so that the code behaves the same.

Quick start & Documentation

Ready to dive in? Check out the documentation.

Join the Community!

https://discord.roblox-ts.com

Games that use roblox-ts

types's Issues

Make generated events readonly

DataStore type definitions incorrect

This needs to be fixed for datastores to be usable

ReadonlyMaps/Sets should get a constructor

I think it is sometimes useful to declare something as a ReadonlyMap/Set, but it would be better if I did not have to use new Map() as ReadonlyMap. I would like to add a constructor to these objects so one can just do new ReadonlyMap() directly.

3rd of NumberSequenceKeypoint is optional

3rd of NumberSequenceKeypoint is optional

NumberSequenceKeypoint Constructors

NumberSequenceKeypoint.new ( number time, number value )
--Creates a keypoint with a specified time and value.

NumberSequenceKeypoint.new ( number time, number value, number envelop )
--Creates a keypoint with a specified time, value, and envelope.

<T = Instance> should be <T extends Instance = Instance>

Where we have generics in things like FindFirstChild, <T = Instance> should be <T extends Instance = Instance>, because it must always be an Instance.

Some class spellings of certain class methods are not supported

For example:

Both CFrame:VectorToObjectSpace(Vector3)) and
CFrame:vectorToObjectSpace(Vector3) are valid in engine, but only the latter spelling is supported by rbx-types.

string.find/string.match should use LuaTuple

string.find/string.match should use LuaTuple

string.match only supports one capture or none

Lua supports multiple captures being returned using string.match, however here there is no return type for multiple captures.

Some CreateableInstances cannot be made with Instance.new

GameSettings, ParabolaAdornment, LuaSettings, PhysicsSettings, Player cannot be instantiated by Instance.new. Could we remove them from showing up in the prompts for new Instance("")? It comes from CreatableInstances

string.byte needs to return tuple

string.byte needs to return tuple.
it returns number now.

Object.keys/values/entries type definitions should be improved

Currently, the Object.keys/values/entries functions don't have the best types for our purposes. I wrote this up and thought we could use something similar to this in es.d.ts once #66 gets merged.

declare function keys<T>(o: Array<T>): Array<number>;
declare function keys<T>(o: Set<T>): Array<T>;
declare function keys<K, V>(o: Map<K, V>): Array<K>;
declare function keys<T>(o: T): Array<keyof T>;

declare function values<T>(o: Array<T>): Array<T>;
declare function values<T>(o: Set<T>): Array<true>;
declare function values<K, V>(o: Map<K, V>): Array<V>;
declare function values<T>(o: T): Array<T[keyof T]>;

declare function entries<T>(o: Array<T>): Array<[number, T]>;
declare function entries<T>(o: Set<T>): Array<[T, true]>;
declare function entries<K, V>(o: Map<K, V>): Array<[K, V]>;
declare function entries<T>(o: T): Array<[keyof T, T[keyof T]]>;

Manual type override to-do list

General

setmetatable should be declared

BasePart

BasePart.Touched param #1 should be BasePart

Players

GetPlayerFromCharacter should return Player | undefined (maybe also accept Model?)
GetPlayerByUserId should return Player | undefined
GetPlayers should return Array<Player>
GetCharacterAppearanceAsync should return Model | undefined
GetCharacterAppearanceInfoAsync could have an interface made for the return type
GetFriendsAsync should return FriendPages
GetUserThumbnailAsync should return a typed tuple

CollectionService

GetTagged could be GetTagged<T = Instance>(tag: string): Array<T>;

math.frexp should return [number, number] instead of number

https://github.com/roblox-ts/rbx-types/blob/b03c964f26b0d0378d1563200b9b7a385a7566a6/include/lua.d.ts#L267

debug.traceback has arguments

https://github.com/roblox-ts/rbx-types/blob/8ff683572ab90583a00ac4d78902cba731e0bbf0/include/lua.d.ts#L138

Should be

	function traceback(message?: string, level?: number): string;
	function traceback(thread: thread, message?: string, level?: number): string;

This is undocumented (unintentionally) - but basically is on parity with 5.1 debug.traceback ([thread,] [message [, level]]) now - according to @LPGhatguy
https://www.lua.org/manual/5.1/manual.html#pdf-debug.traceback

CFrame.toAxisAngle should return tuple instead of array

CFrame.toAxisAngle should return tuple instead of array

output>

local _0 = cframe:toAxisAngle();
local axis, theta = _0[1], _0[2];

GetPropertyChangedSignal should only allow strings of properties

Here is the proper definition I came up with:

type GetProperties<T> = {
	[Key in keyof T]-?: Key extends "GetPropertyChangedSignal"
		? never
		: T[Key] extends RBXScriptSignal
		? never
		: (() => any) extends T[Key]
		? never
		: Key
}[keyof T];

GetPropertyChangedSignal<T extends GetProperties<this>>(property: T): RBXScriptSignal;

GetEnumItems() is not possible to do.

Switch to Rodocs

rodocs/dumpling#21

math.frexp shoule return tuple instead of array

math.frexp shoule return tuple instead of array

expected>

local mantissa, exponent = math.frexp(v);

actually>

local _0 = math.frexp(v);
local mantissa, exponent = _0[1], _0[2];

SocialService.GameInvitePromptClosed event parameter types are incorrect

Rbx-types says that the senderPlayer parameter is a Instance and the recipientIds parameter is any[], while the documentation says senderPlayer is a Player and receipientIds is number[].

UDim2.fromOffset, UDim2.fromScale

Two new static constructors were added for UDim2 but they're not enabled yet.

This issue is a reminder to add them.

interface UDim2Constructor {
	fromOffset(x: number, y: number): UDim2;
	fromScale(x: number, y: number): UDim2;
}

userinputservice inputbegan/ended first argument is an instance rather than an InputObject

Unpick should be Omit

This was my fault. I didn't that much about it.

Add @rbxts server/client back to services

os.date is missing overloads

When calling os.date, it will currently always error if you don't use os.date("*t, x).

This means you can't use it in instances such as:

os.date("!*t") // Current date table in UTC time
os.date("%x") // Current date in MM/DD/YY format

This is among other alternatives as specified in the Lua documentation: https://www.lua.org/pil/22.1.html

string.find should return [number, number] | undefined

from the wiki: If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil

Clone method does not retain type

fallDown is an Animation, but cloning it has Instance as the type, so you must specifiy as Animation to make sure everything lines up.

Services which might deserve @rbxts server/client directives

GuiService
UserInputService
MessagingService
GroupService
TextService.FilterStringAsync
AssetService

Incorrect typings for PromiseLike

https://github.com/roblox-ts/rbx-types/blob/a4b3c2fc5ddcee3acfcf939370dce58fe432c3ac/include/es.d.ts#L680

Signature should match Promise.then

Sort API members based on security level

Possible security levels:

"None" // Default
"LocalUserSecurity" // Command Line
"PluginSecurity" // Plugins
"RobloxScriptSecurity" // CoreScripts
"RobloxSecurity" // ?
"NotAccessibleSecurity" // ?

Higher security levels should include the next lower security level?

Then we can create something like plugin.d.ts which links to include/PluginSecurity.d.ts

gsub should return a LuaTuple

Bad type syllogisms

All Instances are Folders, ValueBases, and a few other similar types. This is bad for a few reasons.

Example 1:

if (myInstance.IsA("Folder")) {
	// Do something with folders
} else if (myInstance.IsA("Part"))
	// Do something with parts
}

Example 1 will error on calling "IsA" in the else if clause, since it is of type "never" after it has been determined not to be a Folder (and since all Instances are Folders, it must not be an instance)

Example 2:

if (myInstance.IsA("Part")) {
	// Do something with parts
} else if (myInstance.IsA("Folder"))
	// Do something with folders
}

Example 2 works as a workaround for this issue in this case—however, this does not work if you have an "else" clause at the end, or are dealing with multiple all-encompassing types (like ValueBase with Folder)

Example 3:

if (myInstance.IsA("Folder")) {
	// Do something with folders
} else {
	print("Found another instance of type" + myInstance.ClassName)
}

Since all Instances are Folders, the example 3 will error, because "myInstance" is of type "never" in the else clause.

To work around this, you must use a type assertion (myInstance as Instance), or something similar, in clauses following all-encompassing type guards

Right now I have some pretty ugly code

JointInstances should have Part0 and Part1 of type BasePart | undefined

For now, I have to assert BasePart | undefined types as BasePart to set a weld's Part0 to nil

When using as typeof X it imports X in lua.

When I say import X and only use it in as typeof X it compiles the import of X into lua (even though it's a type thing).

xpcall not exists

xpcall not exists

Improve definitions for Rbx_Pages

Pages:GetCurrentPage() currently returns unknown.

Unfortunately, it's really hard to define this on a case-by-case basis. Lots of APIs use either Pages or a class that inherits from Pages.

We should convert the class to be a generic class (Rbx_Pages<T = unknown>) so that we can override it per API.

The new type definition for Rbx_Pages.GetCurrentPage() would look like:

interface Rbx_Pages<T = unknown> extends Rbx_Instance {
    Rbx_Pages.GetCurrentPage(): T;
}

`this` parameter should be added to all methods

Adding a this parameter would be a quick and easy way of ensuring that object methods are never called improperly.

Example:

const { FindFirstChild } = part;
FindFirstChild("Hello");
// ERROR: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Instance'.

Every method should be assigned a this which is the class in which it is defined. E.g.

Camera.GetTiltSpeed(): number
// should be
Camera.GetTiltSpeed(this: Camera): number

'sub' does not exist on types 'UDim2' and 'UDim'

Like the title suggests, these methods are not defined in rbx-types, even though their respective 'add' methods are.

E.g.:
new UDim2(3, 3, 3, 3).add(new UDim2(2, 2, 2, 2));
works just fine, while
new UDim2(3, 3, 3, 3).sub(new UDim2(2, 2, 2, 2));
gives the error "Property 'sub' does not exist on type 'UDim2'"

These should be implemented since they are part of the functionality of the respective types (see UDim and UDim2

customDefinitions.d.ts is being bundled with rbx-types

customDefinitions.d.ts is not supposed to be bundled with rbx-types. Everything in it is already copied into generated_classes.d.ts

needs to change MakeSystemMessageConfig.FontSize to TextSize

https://devforum.roblox.com/t/chatmakesystemmessage-fontsize-not-changing-font-size/141568/2

API document is wrong

UserInputService TouchMoved/TouchStarted/TouchEnded first arguments is an InputObject rather than an instance

lua's ts.string is missing necessary functions

string.find, string.sub, etc.

RemoteFunction OnServerInvoke, OnClientInvoke, InvokeClient & InvokeServer use any[]

not sure if this is intentional, but it does not follow the unknown rule that RemoteEvents seem to follow.

Promise.resolve() and Promise.reject

Promise.resolve(); // actually: error
// expected: no error

let prom:Promise<void> = Promise.reject('asdfasdf'); // actually: error
// expected: no error

Vector3.Lerp and CFrame.lerp have inconsistent capitalizations

CFrame.Lerp is the title preferred by Roblox documentation. This makes functions expecting something with the "lerp" method unable to take Vector3, and functions expecting something with the "Lerp" method unable to take CFrame, despite the fact that these methods have identical signatures and (essentially the same) behavior.

Color3.ToHSV should be a LuaTuple

`version` is a function, not string

global version is a function which returns a string, not a string.

version: () => string

FindPartOnRay should return BasePart | undefined instead of BasePart

PreloadAsync needs an array of instances and not an array of strings

https://github.com/roblox-ts/rbx-types/blob/29a2eff2e73d6f646b80b58b86d4f6896579be8d/include/manual.d.ts#L106

Implement instances as classes to hide _N properties

declare namespace _Instances {
  class _Instance {
    private _0: never
    Name: string

    IsA(x: "Instance"): this is Instance
    IsA(x: "Folder"): this is Folder
  }

  class _Folder extends _Instance {
    private _1: never
  }
}

interface Instance extends _Instances._Instance {}

interface Folder extends _Instances._Folder {}

const x = {} as Instance

if (x.IsA("Folder")) {
  x // Folder
} else {
  x // Instance
}