lune/types/roblox.luau

export type DatabaseScriptability = "None" | "Custom" | "Read" | "ReadWrite" | "Write"

export type DatabasePropertyTag =
	"Deprecated"
	| "Hidden"
	| "NotBrowsable"
	| "NotReplicated"
	| "NotScriptable"
	| "ReadOnly"
	| "WriteOnly"

export type DatabaseClassTag =
	"Deprecated"
	| "NotBrowsable"
	| "NotCreatable"
	| "NotReplicated"
	| "PlayerReplicated"
	| "Service"
	| "Settings"
	| "UserSettings"

export type DatabaseProperty = {
	--[=[
		The name of the property.
	]=]
	Name: string,
	--[=[
		The datatype of the property.

		For normal datatypes this will be a string such as `string`, `Color3`, ...

		For enums this will be a string formatted as `Enum.EnumName`.
	]=]
	Datatype: string,
	--[=[
		The scriptability of this property, meaning if it can be written / read at runtime.

		All properties are writable and readable in Lune even if scriptability is not.
	]=]
	Scriptability: DatabaseScriptability,
	--[=[
		Tags describing the property.

		These include information such as if the property can be replicated to players
		at runtime, if the property should be hidden in Roblox Studio, and more.
	]=]
	Tags: { DatabasePropertyTag },
}

export type DatabaseClass = {
	--[=[
		The name of the class.
	]=]
	Name: string,
	--[=[
		The superclass (parent class) of this class.

		May be nil if no parent class exists.
	]=]
	Superclass: string?,
	--[=[
		Known properties for this class.
	]=]
	Properties: { [string]: DatabaseProperty },
	--[=[
		Default values for properties of this class.

		Note that these default properties use Lune's built-in datatype
		userdatas, and that if there is a new datatype that Lune does
		not yet know about, it may be missing from this table.
	]=]
	DefaultProperties: { [string]: any },
	--[=[
		Tags describing the class.

		These include information such as if the class can be replicated
		to players at runtime, and top-level class categories.
	]=]
	Tags: { DatabaseClassTag },
}

export type DatabaseEnum = {
	--[=[
		The name of this enum, for example `PartType` or `UserInputState`.
	]=]
	Name: string,
	--[=[
		Members of this enum.

		Note that this is a direct map of name -> enum values,
		and does not actually use the EnumItem datatype itself.
	]=]
	Items: { [string]: number },
}

export type Database = {
	--[=[
		The current version of the reflection database.

		This will follow the format `x.y.z.w`, which most commonly looks something like `0.567.0.123456789`
	]=]
	Version: string,
	--[=[
		Retrieves a list of all currently known class names.
	]=]
	GetClassNames: (self: Database) -> { string },
	--[=[
		Retrieves a list of all currently known enum names.
	]=]
	GetEnumNames: (self: Database) -> { string },
	--[=[
		Gets a class with the exact given name, if one exists.
	]=]
	GetClass: (self: Database, name: string) -> DatabaseClass?,
	--[=[
		Gets an enum with the exact given name, if one exists.
	]=]
	GetEnum: (self: Database, name: string) -> DatabaseEnum?,
	--[=[
		Finds a class with the given name.

		This will use case-insensitive matching and ignore leading and trailing whitespace.
	]=]
	FindClass: (self: Database, name: string) -> DatabaseClass?,
	--[=[
		Finds an enum with the given name.

		This will use case-insensitive matching and ignore leading and trailing whitespace.
	]=]
	FindEnum: (self: Database, name: string) -> DatabaseEnum?,
}

type InstanceProperties = {
	Parent: Instance?,
	ClassName: string,
	Name: string,
	-- FIXME: This breaks intellisense, but we need some way to access
	-- instance properties without casting the entire instance to any...
	-- [string]: any,
}

type InstanceMetatable = {
	Clone: (self: Instance) -> Instance,
	Destroy: (self: Instance) -> (),
	ClearAllChildren: (self: Instance) -> (),

	GetChildren: (self: Instance) -> { Instance },
	GetDescendants: (self: Instance) -> { Instance },
	GetFullName: (self: Instance) -> string,

	FindFirstAncestor: (self: Instance, name: string) -> Instance?,
	FindFirstAncestorOfClass: (self: Instance, className: string) -> Instance?,
	FindFirstAncestorWhichIsA: (self: Instance, className: string) -> Instance?,
	FindFirstChild: (self: Instance, name: string, recursive: boolean?) -> Instance?,
	FindFirstChildOfClass: (self: Instance, className: string, recursive: boolean?) -> Instance?,
	FindFirstChildWhichIsA: (self: Instance, className: string, recursive: boolean?) -> Instance?,

	IsA: (self: Instance, className: string) -> boolean,
	IsAncestorOf: (self: Instance, descendant: Instance) -> boolean,
	IsDescendantOf: (self: Instance, ancestor: Instance) -> boolean,

	GetAttribute: (self: Instance, name: string) -> any,
	GetAttributes: (self: Instance) -> { [string]: any },
	SetAttribute: (self: Instance, name: string, value: any) -> (),

	GetTags: (self: Instance) -> { string },
	HasTag: (self: Instance, name: string) -> boolean,
	AddTag: (self: Instance, name: string) -> (),
	RemoveTag: (self: Instance, name: string) -> (),
}

export type Instance = typeof(setmetatable(
	(nil :: any) :: InstanceProperties,
	(nil :: any) :: { __index: InstanceMetatable }
))

export type DataModelProperties = {}
export type DataModelMetatable = {
	GetService: (self: DataModel, name: string) -> Instance,
	FindService: (self: DataModel, name: string) -> Instance?,
}

export type DataModel =
	Instance
	& typeof(setmetatable(
		(nil :: any) :: DataModelProperties,
		(nil :: any) :: { __index: DataModelMetatable }
	))

--[=[
	@class Roblox

	Built-in library for manipulating Roblox place & model files

	### Example usage

	```lua
	local fs = require("@lune/fs")
	local roblox = require("@lune/roblox")

	-- Reading a place file
	local placeFile = fs.readFile("myPlaceFile.rbxl")
	local game = roblox.deserializePlace(placeFile)

	-- Manipulating and reading instances - just like in Roblox!
	local workspace = game:GetService("Workspace")
	for _, child in workspace:GetChildren() do
		print("Found child " .. child.Name .. " of class " .. child.ClassName)
	end

	-- Writing a place file
	local newPlaceFile = roblox.serializePlace(game)
	fs.writeFile("myPlaceFile.rbxl", newPlaceFile)
	```
]=]
local roblox = {}

--[=[
	@within Roblox
	@tag must_use

	Deserializes a place into a DataModel instance.

	This function accepts a string of contents, *not* a file path.
	If reading a place file from a file path is desired, `fs.readFile`
	can be used and the resulting string may be passed to this function.

	### Example usage

	```lua
	local fs = require("@lune/fs")
	local roblox = require("@lune/roblox")

	local placeFile = fs.readFile("filePath.rbxl")
	local game = roblox.deserializePlace(placeFile)
	```

	@param contents The contents of the place to read
]=]
function roblox.deserializePlace(contents: string): DataModel
	return nil :: any
end

--[=[
	@within Roblox
	@tag must_use

	Deserializes a model into an array of instances.

	This function accepts a string of contents, *not* a file path.
	If reading a model file from a file path is desired, `fs.readFile`
	can be used and the resulting string may be passed to this function.

	### Example usage

	```lua
	local fs = require("@lune/fs")
	local roblox = require("@lune/roblox")

	local modelFile = fs.readFile("filePath.rbxm")
	local instances = roblox.deserializeModel(modelFile)
	```

	@param contents The contents of the model to read
]=]
function roblox.deserializeModel(contents: string): { Instance }
	return nil :: any
end

--[=[
	@within Roblox
	@tag must_use

	Serializes a place from a DataModel instance.

	This string can then be written to a file, or sent over the network.

	### Example usage

	```lua
	local fs = require("@lune/fs")
	local roblox = require("@lune/roblox")

	local placeFile = roblox.serializePlace(game)
	fs.writeFile("filePath.rbxl", placeFile)
	```

	@param dataModel The DataModel for the place to serialize
	@param xml If the place should be serialized as xml or not. Defaults to `false`, meaning the place gets serialized using the binary format and not xml.
]=]
function roblox.serializePlace(dataModel: DataModel, xml: boolean?): string
	return nil :: any
end

--[=[
	@within Roblox
	@tag must_use

	Serializes one or more instances as a model.

	This string can then be written to a file, or sent over the network.

	### Example usage

	```lua
	local fs = require("@lune/fs")
	local roblox = require("@lune/roblox")

	local modelFile = roblox.serializeModel({ instance1, instance2, ... })
	fs.writeFile("filePath.rbxm", modelFile)
	```

	@param instances The array of instances to serialize
	@param xml If the model should be serialized as xml or not. Defaults to `false`, meaning the model gets serialized using the binary format and not xml.
]=]
function roblox.serializeModel(instances: { Instance }, xml: boolean?): string
	return nil :: any
end

--[=[
	@within Roblox
	@tag must_use

	Gets the current auth cookie, for usage with Roblox web APIs.

	Note that this auth cookie is formatted for use as a "Cookie" header,
	and that it contains restrictions so that it may only be used for
	official Roblox endpoints. To get the raw cookie value without any
	additional formatting, you can pass `true` as the first and only parameter.

	### Example usage

	```lua
	local roblox = require("@lune/roblox")
	local net = require("@lune/net")

	local cookie = roblox.getAuthCookie()
	assert(cookie ~= nil, "Failed to get roblox auth cookie")

	local myPrivatePlaceId = 1234567890

	local response = net.request({
		url = "https://assetdelivery.roblox.com/v2/assetId/" .. tostring(myPrivatePlaceId),
		headers = {
			Cookie = cookie,
		},
	})

	local responseTable = net.jsonDecode(response.body)
	local responseLocation = responseTable.locations[1].location
	print("Download link to place: " .. responseLocation)
	```

	@param raw If the cookie should be returned as a pure value or not. Defaults to false
]=]
function roblox.getAuthCookie(raw: boolean?): string?
	return nil :: any
end

--[=[
	@within Roblox
	@tag must_use

	Gets the bundled reflection database.

	This database contains information about Roblox enums, classes, and their properties.

	### Example usage

	```lua
	local roblox = require("@lune/roblox")

	local db = roblox.getReflectionDatabase()

	print("There are", #db:GetClassNames(), "classes in the reflection database")

	print("All base instance properties:")

	local class = db:GetClass("Instance")
	for name, prop in class.Properties do
		print(string.format(
			"- %s with datatype %s and default value %s",
			prop.Name,
			prop.Datatype,
			tostring(class.DefaultProperties[prop.Name])
		))
	end
	```
]=]
function roblox.getReflectionDatabase(): Database
	return nil :: any
end

-- TODO: Make typedefs for all of the datatypes as well...
roblox.Instance = (nil :: any) :: {
	new: ((className: "DataModel") -> DataModel) & ((className: string) -> Instance),
}

return roblox