@flamework-experimental/core 2.0.0-alpha.0

package/out/reflect.luau

@@ -0,0 +1,310 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Reflection/metadata API
+	 
+]]
+local Reflect = {}
+do
+	local _container = Reflect
+	--* object -> property -> key -> value 
+	local metadata = setmetatable({}, {
+		__mode = "k",
+	})
+	local NO_PROP_MARKER = {}
+	local function getObjMetadata(obj, prop, create)
+		local _condition = prop
+		if _condition == nil then
+			_condition = NO_PROP_MARKER
+		end
+		local realProp = _condition
+		if create then
+			local _obj = obj
+			local objMetadata = metadata[_obj]
+			if not objMetadata then
+				local _exp = obj
+				objMetadata = {}
+				local _objMetadata = objMetadata
+				metadata[_exp] = _objMetadata
+			end
+			local propMetadata = objMetadata[realProp]
+			if not propMetadata then
+				local _objMetadata = objMetadata
+				propMetadata = {}
+				local _propMetadata = propMetadata
+				_objMetadata[realProp] = _propMetadata
+			end
+			return propMetadata
+		else
+			local _obj = obj
+			local _result = metadata[_obj]
+			if _result ~= nil then
+				_result = _result[realProp]
+			end
+			return _result
+		end
+	end
+	local function getParentConstructor(obj)
+		local metatable = getmetatable(obj)
+		if metatable and type(metatable) == "table" then
+			return rawget(metatable, "__index")
+		end
+	end
+	--[[
+		*
+		     * Apply metadata onto this object.
+		     
+	]]
+	local function defineMetadata(obj, key, value, property)
+		local metadata = getObjMetadata(obj, property, true)
+		local _key = key
+		local _value = value
+		metadata[_key] = _value
+	end
+	_container.defineMetadata = defineMetadata
+	--[[
+		*
+		     * Apply metadata in batch onto this object.
+		     
+	]]
+	local function defineMetadataBatch(obj, list, property)
+		local metadata = getObjMetadata(obj, property, true)
+		for key, value in pairs(list) do
+			metadata[key] = value
+		end
+	end
+	_container.defineMetadataBatch = defineMetadataBatch
+	--[[
+		*
+		     * Delete metadata from this object.
+		     
+	]]
+	local function deleteMetadata(obj, key, property)
+		local metadata = getObjMetadata(obj, property)
+		local _result = metadata
+		if _result ~= nil then
+			local _key = key
+			_result[_key] = nil
+		end
+	end
+	_container.deleteMetadata = deleteMetadata
+	--[[
+		*
+		     * Get metadata from this object.
+		     * Type parameter is an assertion.
+		     
+	]]
+	local function getOwnMetadata(obj, key, property)
+		local metadata = getObjMetadata(obj, property)
+		local _result = metadata
+		if _result ~= nil then
+			local _key = key
+			_result = _result[_key]
+		end
+		return _result
+	end
+	_container.getOwnMetadata = getOwnMetadata
+	--[[
+		*
+		     * Check if this object has the specified metadata key.
+		     
+	]]
+	local function hasOwnMetadata(obj, key, property)
+		local metadata = getObjMetadata(obj, property)
+		local _result = metadata
+		if _result ~= nil then
+			local _key = key
+			_result = _result[_key] ~= nil
+		end
+		local _condition = _result
+		if _condition == nil then
+			_condition = false
+		end
+		return _condition
+	end
+	_container.hasOwnMetadata = hasOwnMetadata
+	--[[
+		*
+		     * Retrieve all metadata keys for this object.
+		     
+	]]
+	local function getOwnMetadataKeys(obj, property)
+		local metadata = getObjMetadata(obj, property)
+		local keys = {}
+		local _result = metadata
+		if _result ~= nil then
+			-- ▼ ReadonlyMap.forEach ▼
+			local _callback = function(_, key)
+				local _key = key
+				table.insert(keys, _key)
+				return #keys
+			end
+			for _k, _v in _result do
+				_callback(_v, _k, _result)
+			end
+			-- ▲ ReadonlyMap.forEach ▲
+		end
+		return keys
+	end
+	_container.getOwnMetadataKeys = getOwnMetadataKeys
+	--[[
+		*
+		     * Retrieves all properties (that contain metadata) on this object.
+		     
+	]]
+	local function getOwnProperties(obj)
+		local _obj = obj
+		local properties = metadata[_obj]
+		if not properties then
+			return {}
+		end
+		local keys = {}
+		for key in properties do
+			if key ~= NO_PROP_MARKER then
+				table.insert(keys, key)
+			end
+		end
+		return keys
+	end
+	_container.getOwnProperties = getOwnProperties
+	--[[
+		*
+		     * Retrieve all values for the specified key from the object and its parents.
+		     * Type parameter is an assertion.
+		     
+	]]
+	local function getMetadatas(obj, key, property)
+		local values = {}
+		local value = getOwnMetadata(obj, key, property)
+		if value ~= nil then
+			table.insert(values, value)
+		end
+		local parent = getParentConstructor(obj)
+		if parent then
+			local _exp = getMetadatas(parent, key, property)
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback = function(value)
+				local _value = value
+				table.insert(values, _value)
+				return #values
+			end
+			for _k, _v in _exp do
+				_callback(_v, _k - 1, _exp)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+		end
+		return values
+	end
+	_container.getMetadatas = getMetadatas
+	--[[
+		*
+		     * Get metadata from this object or its parents.
+		     * Type parameter is an assertion.
+		     
+	]]
+	local function getMetadata(obj, key, property)
+		local value = getOwnMetadata(obj, key, property)
+		if value ~= nil then
+			return value
+		end
+		local parent = getParentConstructor(obj)
+		if parent then
+			return getMetadata(parent, key, property)
+		end
+	end
+	_container.getMetadata = getMetadata
+	--[[
+		*
+		     * Check if this object or any of its parents has the specified metadata key.
+		     
+	]]
+	local function hasMetadata(obj, key, property)
+		local value = hasOwnMetadata(obj, key, property)
+		if value then
+			return value
+		end
+		local parent = getParentConstructor(obj)
+		if parent then
+			return hasMetadata(parent, key, property)
+		end
+		return false
+	end
+	_container.hasMetadata = hasMetadata
+	--[[
+		*
+		     * Retrieve all metadata keys for this object and its parents.
+		     
+	]]
+	local function getMetadataKeys(obj, property)
+		local _set = {}
+		for _, _v in getOwnMetadataKeys(obj, property) do
+			_set[_v] = true
+		end
+		local keys = _set
+		local parent = getParentConstructor(obj)
+		if parent then
+			local _exp = getMetadataKeys(parent, property)
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback = function(key)
+				local _key = key
+				keys[_key] = true
+				return keys
+			end
+			for _k, _v in _exp do
+				_callback(_v, _k - 1, _exp)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+		end
+		local _array = {}
+		local _length = #_array
+		for _v in keys do
+			_length += 1
+			_array[_length] = _v
+		end
+		return _array
+	end
+	_container.getMetadataKeys = getMetadataKeys
+	--[[
+		*
+		     * Retrieves all properties (that contain metadata) on this object and its parents.
+		     
+	]]
+	local function getProperties(obj)
+		local _set = {}
+		for _, _v in getOwnProperties(obj) do
+			_set[_v] = true
+		end
+		local keys = _set
+		local parent = getParentConstructor(obj)
+		if parent then
+			local _exp = getProperties(parent)
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback = function(key)
+				local _key = key
+				keys[_key] = true
+				return keys
+			end
+			for _k, _v in _exp do
+				_callback(_v, _k - 1, _exp)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+		end
+		local _array = {}
+		local _length = #_array
+		for _v in keys do
+			_length += 1
+			_array[_length] = _v
+		end
+		return _array
+	end
+	_container.getProperties = getProperties
+	--* @hidden Internal use, do not use 
+	local function resetObject(object)
+		local _object = object
+		metadata[_object] = nil
+	end
+	_container.resetObject = resetObject
+end
+return {
+	Reflect = Reflect,
+}

package/out/serialization/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Types for Flamework's static serialization. There is no runtime here: the transformer generates
+ * the encode and decode code for each type at the call site, straight `buffer` reads and writes with
+ * nothing describing the type left in the output.
+ */
+export declare namespace Serialization {
+    /** What `Flamework.createSerializer<T>()` returns. */
+    interface Serializer<T> {
+        /**
+         * Encodes `value`. The second result is the blob list: values with no buffer representation
+         * (Instances, `unknown`, most Roblox datatypes), referenced from the buffer by index. It is
+         * `undefined` when the type has no such values, and a table (possibly empty) when it has.
+         */
+        serialize: (value: T) => LuaTuple<[buffer, Array<defined> | undefined]>;
+        /**
+         * Decodes a payload produced by {@link serialize}. Raises on malformed input, so wrap it in
+         * `pcall` for data from an untrusted peer; the networking package does.
+         */
+        deserialize: (payload: buffer, blobs?: Array<defined>) => T;
+    }
+    /**
+     * Decodes a packed argument list, which is how networking unpacks what a remote delivered. One is
+     * generated per event and function; the matching encoding is generated inline at every call
+     * site, so no encoder exists as a value at runtime.
+     */
+    type Decoder<T extends Array<unknown> = Array<unknown>> = (payload: buffer, blobs: Array<defined>) => T;
+    /** An unsigned byte, 0 to 255. */
+    type u8 = number & {
+        readonly __brand: "u8";
+    };
+    /** A signed byte, -128 to 127. */
+    type i8 = number & {
+        readonly __brand: "i8";
+    };
+    /** An unsigned 16-bit integer, 0 to 65535. */
+    type u16 = number & {
+        readonly __brand: "u16";
+    };
+    /** A signed 16-bit integer, -32768 to 32767. */
+    type i16 = number & {
+        readonly __brand: "i16";
+    };
+    /** An unsigned 32-bit integer. */
+    type u32 = number & {
+        readonly __brand: "u32";
+    };
+    /** A signed 32-bit integer. */
+    type i32 = number & {
+        readonly __brand: "i32";
+    };
+    /** A single-precision float: four bytes, about seven significant digits. */
+    type f32 = number & {
+        readonly __brand: "f32";
+    };
+    /** A double-precision float, which is what a plain `number` is written as. */
+    type f64 = number & {
+        readonly __brand: "f64";
+    };
+    /**
+     * A non-negative integer written as a LEB128 varint: one byte below 128, two below 16384, up to
+     * five bytes. The right choice for counts, ids and other small-most-of-the-time integers.
+     */
+    type varint = number & {
+        readonly __brand: "varint";
+    };
+    /** A string of at most 255 bytes: a fixed one-byte length. */
+    type string8 = string & {
+        readonly __brand: "u8_string";
+    };
+    /** A string of at most 65535 bytes: a fixed two-byte length. */
+    type string16 = string & {
+        readonly __brand: "u16_string";
+    };
+    /** A string with a fixed four-byte length. */
+    type string32 = string & {
+        readonly __brand: "u32_string";
+    };
+    /** A buffer of at most 65535 bytes: a fixed two-byte length. */
+    type buffer16 = buffer & {
+        readonly __brand: "u16_buffer";
+    };
+    /** A buffer with a fixed four-byte length. */
+    type buffer32 = buffer & {
+        readonly __brand: "u32_buffer";
+    };
+}

package/out/serialization/types.luau

@@ -0,0 +1,9 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Types for Flamework's static serialization. There is no runtime here: the transformer generates
+	 * the encode and decode code for each type at the call site, straight `buffer` reads and writes with
+	 * nothing describing the type left in the output.
+	 
+]]
+return nil

package/out/utility/constructors.d.ts

@@ -0,0 +1,4 @@
+export type Constructor<T = object> = new (...args: never[]) => T;
+export type AbstractConstructor<T = object> = abstract new (...args: never[]) => T;
+export declare function isConstructor(obj: object): obj is Constructor;
+export declare function isAbstractConstructor(obj: object): obj is AbstractConstructor;

package/out/utility/constructors.luau

@@ -0,0 +1,12 @@
+-- Compiled with roblox-ts v3.0.0
+local isAbstractConstructor
+local function isConstructor(obj)
+	return isAbstractConstructor(obj) and obj.new ~= nil
+end
+function isAbstractConstructor(obj)
+	return obj.constructor ~= nil
+end
+return {
+	isConstructor = isConstructor,
+	isAbstractConstructor = isAbstractConstructor,
+}

package/out/utility/convertConciseDependencyInfo.d.ts

@@ -0,0 +1,5 @@
+import type { Modding } from "../modding";
+/**
+ * Converts concise dependency info into `Modding.DependencyInfo`
+ */
+export declare function convertConciseDependencyInfo(dependency?: string | Modding.DependencyInfo): Modding.DependencyInfo;

package/out/utility/convertConciseDependencyInfo.luau

@@ -0,0 +1,29 @@
+-- Compiled with roblox-ts v3.0.0
+local cachedDependencyInfo = {}
+--[[
+	*
+	 * Converts concise dependency info into `Modding.DependencyInfo`
+	 
+]]
+local function convertConciseDependencyInfo(dependency)
+	local _arg0 = dependency ~= nil
+	assert(_arg0)
+	local _dependency = dependency
+	if type(_dependency) == "string" then
+		local _dependency_1 = dependency
+		local metadata = cachedDependencyInfo[_dependency_1]
+		if not metadata then
+			local _exp = dependency
+			metadata = {
+				id = dependency,
+			}
+			local _metadata = metadata
+			cachedDependencyInfo[_exp] = _metadata
+		end
+		return metadata
+	end
+	return dependency
+end
+return {
+	convertConciseDependencyInfo = convertConciseDependencyInfo,
+}

package/out/utility/getClassImplements.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The interfaces a class implements, own and inherited, each once: the transformer writes every
+ * class's own heritage clause, so a subclass that re-declares an interface its parent implements
+ * carries the id twice up the chain, and attached to it twice -- the lifecycle's ordered lists ran
+ * `onInit` and `onStart` twice for it.
+ */
+export declare function getClassImplements(constructor: object): string[];

package/out/utility/getClassImplements.luau

@@ -0,0 +1,27 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+--[[
+	*
+	 * The interfaces a class implements, own and inherited, each once: the transformer writes every
+	 * class's own heritage clause, so a subclass that re-declares an interface its parent implements
+	 * carries the id twice up the chain, and attached to it twice -- the lifecycle's ordered lists ran
+	 * `onInit` and `onStart` twice for it.
+	 
+]]
+local function getClassImplements(constructor)
+	local classImplements = {}
+	local seen = {}
+	for _, implementList in Reflect.getMetadatas(constructor, "flamework:implements") do
+		for _1, implementId in implementList do
+			if not (seen[implementId] ~= nil) then
+				seen[implementId] = true
+				table.insert(classImplements, implementId)
+			end
+		end
+	end
+	return classImplements
+end
+return {
+	getClassImplements = getClassImplements,
+}

package/out/utility/getClassesInPath.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Requires one ModuleScript through the roblox-ts runtime, as an `import` would, and returns what
+ * it exported. A module that fails to load raises with its full name and how long it took.
+ */
+export declare function importModule(moduleScript: ModuleScript): defined | undefined;
+/**
+ * Requires every ModuleScript at and under the specified Rojo path, in tree order, and returns
+ * what each exported, leaving out the ones that exported nothing. This is the loading half of
+ * {@link getClassesInPath}; a plugin whose modules register themselves as a side effect of loading
+ * -- test files, say -- only needs this half.
+ *
+ * The path is relative to the tree's root (`game` in a place, the model's root in a plugin), which
+ * `resolveRbxPath` finds.
+ */
+export declare function requireModulesInPath(rbxPath: readonly string[]): Array<defined>;
+/**
+ * Requires every ModuleScript at and under the specified Rojo path and returns every exported value
+ * that carries its own Flamework identifier.
+ *
+ * A module that fails to load raises, as it did in v1: a class that silently fails to register
+ * would otherwise only show up later as an unresolvable dependency, far from the cause.
+ */
+export declare function getClassesInPath(rbxPath: readonly string[]): Array<object>;

package/out/utility/getClassesInPath.luau

@@ -0,0 +1,91 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local tsImport = TS.import(script, script.Parent, "tsImport").tsImport
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local resolveRbxPath = TS.import(script, script.Parent, "pathRoot").resolveRbxPath
+--[[
+	*
+	 * Requires one ModuleScript through the roblox-ts runtime, as an `import` would, and returns what
+	 * it exported. A module that fails to load raises with its full name and how long it took.
+	 
+]]
+local function importModule(moduleScript)
+	local start = os.clock()
+	local success, value = pcall(function()
+		return tsImport(moduleScript)
+	end)
+	local endTime = math.floor((os.clock() - start) * 1000)
+	if not success then
+		error(`{moduleScript:GetFullName()} failed to load ({endTime}ms): {value}`, 0)
+	end
+	return value
+end
+--[[
+	*
+	 * Requires every ModuleScript at and under the specified Rojo path, in tree order, and returns
+	 * what each exported, leaving out the ones that exported nothing. This is the loading half of
+	 * {@link getClassesInPath}; a plugin whose modules register themselves as a side effect of loading
+	 * -- test files, say -- only needs this half.
+	 *
+	 * The path is relative to the tree's root (`game` in a place, the model's root in a plugin), which
+	 * `resolveRbxPath` finds.
+	 
+]]
+local function requireModulesInPath(rbxPath)
+	local _rbxPath = rbxPath
+	assert(_rbxPath)
+	local preloadPath = resolveRbxPath(rbxPath)
+	local loaded = {}
+	if preloadPath:IsA("ModuleScript") then
+		local value = importModule(preloadPath)
+		if value ~= nil then
+			table.insert(loaded, value)
+		end
+	end
+	for _, instance in preloadPath:GetDescendants() do
+		if instance:IsA("ModuleScript") then
+			local value = importModule(instance)
+			if value ~= nil then
+				table.insert(loaded, value)
+			end
+		end
+	end
+	return loaded
+end
+--[[
+	*
+	 * Requires every ModuleScript at and under the specified Rojo path and returns every exported value
+	 * that carries its own Flamework identifier.
+	 *
+	 * A module that fails to load raises, as it did in v1: a class that silently fails to register
+	 * would otherwise only show up later as an unresolvable dependency, far from the cause.
+	 
+]]
+local function getClassesInPath(rbxPath)
+	local foundClasses = {}
+	for _, value in requireModulesInPath(rbxPath) do
+		if not (type(value) == "table") then
+			continue
+		end
+		-- This is an `export =` on a Flamework class.
+		if Reflect.hasOwnMetadata(value, "identifier") then
+			table.insert(foundClasses, value)
+			continue
+		end
+		for _1, member in pairs(value) do
+			-- This is an `export` on a Flamework class.
+			--
+			-- Own metadata only: an undecorated subclass inherits its parent's identifier, and
+			-- must not be mistaken for a registered class of its own.
+			if type(member) == "table" and Reflect.hasOwnMetadata(member, "identifier") then
+				table.insert(foundClasses, member)
+			end
+		end
+	end
+	return foundClasses
+end
+return {
+	importModule = importModule,
+	requireModulesInPath = requireModulesInPath,
+	getClassesInPath = getClassesInPath,
+}

package/out/utility/globs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the Rojo paths a compile-time glob resolved to.
+ */
+export declare function getGlobPaths(glob: string): string[][];
+/**
+ * Requires every ModuleScript under every path the glob matched and returns the exported classes,
+ * each at most once.
+ */
+export declare function getClassesInGlob(glob: string): Array<object>;

package/out/utility/globs.luau

@@ -0,0 +1,64 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local getClassesInPath = TS.import(script, script.Parent, "getClassesInPath").getClassesInPath
+local findMetadataContainer = TS.import(script, script.Parent, "metadata").findMetadataContainer
+--[[
+	*
+	 * The shape of `include/flamework/globs.json`, which the transformer writes for game projects.
+	 *
+	 * Keys are the glob strings exactly as they appear in the emitted code (obfuscated when obfuscation
+	 * is on); values are the Rojo paths that matched them at compile time.
+	 
+]]
+local globContainer
+--[[
+	*
+	 * Returns the Rojo paths a compile-time glob resolved to.
+	 
+]]
+local function getGlobPaths(glob)
+	if globContainer == nil then
+		local _condition = findMetadataContainer("globs")
+		if _condition == nil then
+			_condition = false
+		end
+		globContainer = _condition
+	end
+	local _result
+	if globContainer == false then
+		_result = nil
+	else
+		local _result_1 = globContainer.game
+		if _result_1 ~= nil then
+			local _glob = glob
+			_result_1 = _result_1[_glob]
+		end
+		_result = _result_1
+	end
+	local paths = _result
+	if paths == nil then
+		error(`Flamework has no paths for the glob '{glob}'. ` .. "Globs are resolved at compile time into include/flamework/globs.json, which only game projects emit; " .. "make sure the include directory is part of your Rojo project and that the glob matched at least one file.", 0)
+	end
+	return paths
+end
+--[[
+	*
+	 * Requires every ModuleScript under every path the glob matched and returns the exported classes,
+	 * each at most once.
+	 
+]]
+local function getClassesInGlob(glob)
+	local classes = {}
+	for _, path in getGlobPaths(glob) do
+		for _1, found in getClassesInPath(path) do
+			if not (table.find(classes, found) ~= nil) then
+				table.insert(classes, found)
+			end
+		end
+	end
+	return classes
+end
+return {
+	getGlobPaths = getGlobPaths,
+	getClassesInGlob = getClassesInGlob,
+}