@flamework-experimental/core 2.0.0-alpha.0

package/out/module/moduleBuilder.d.ts

@@ -0,0 +1,88 @@
+import { Modding } from "../modding";
+import { ModuleDefinition, ProviderConfig, type IgniteOptions, type ProviderRegistrationOptions } from "./moduleDefinition";
+import type { Constructor } from "../utility/constructors";
+import { type PluginDefinition } from "../plugin/pluginDefinition";
+import type { ScopeCondition } from "./scopes";
+type GenericId<T> = string | Modding.Target.Id<T>;
+export declare class ModuleBuilder {
+    /** A global count of the number of module builders. Used to disambiguate identical module debug names. */
+    private static moduleCount;
+    private moduleIndex;
+    private module;
+    constructor();
+    /**
+     * Includes a plugin in this module: its setup runs against every ignition of the module, before
+     * any provider is constructed.
+     *
+     * A plugin is set up once per ignition however many times it is included, so including one
+     * twice is not an error; it is simply not recorded twice.
+     *
+     * With a scope condition, the plugin is set up only in a build where the condition holds, and
+     * is otherwise left out entirely, hooks and all.
+     */
+    includePlugin(plugin: PluginDefinition, options?: ScopeCondition): this;
+    /**
+     * Leaves out the `LifecyclePlugin` every module otherwise starts with, so that nothing in this
+     * module receives `onInit`, `onStart` or the per-frame events. Silent by design: a module that
+     * wants no lifecycle has nothing to be told.
+     */
+    disableDefaultLifecycle(): this;
+    /**
+     * Sets the debug name for this module.
+     *
+     * if a number is provided, a debug name will be generated using the debug info at the level (relative to the caller.)
+     */
+    setDebugName(debugNameOrLevel: string | number): this;
+    /**
+     * Register all providers under the specified path and its descendants.
+     *
+     * The providers must be exported, and must carry the `@Provider()` decorator themselves: an
+     * undecorated subclass of a provider is not registered.
+     *
+     * The options apply to every provider found: a scope condition here scopes the whole folder.
+     *
+     * @metadata macro
+     */
+    registerProviders<T extends string>(_stringPath: T, options?: ProviderRegistrationOptions, path?: Modding.Intrinsic<"path", [T], string[]>): this;
+    /**
+     * Register all providers under every path matched by the specified glob, which is resolved at
+     * compile time.
+     *
+     * This is the v2 equivalent of v1's `Flamework.addPathsGlob`. Globs can match a large number of
+     * paths, so keep them as specific as possible.
+     *
+     * @metadata macro
+     */
+    registerProvidersGlob<T extends string>(_glob: T, options?: ProviderRegistrationOptions, glob?: Modding.Intrinsic<"pathglob", [T], string>): this;
+    private registerProviderClasses;
+    /**
+     * Register a new provider.
+     *
+     * Two registrations may share an id when their scope conditions keep at most one of them in
+     * any one build; both being kept is refused at ignition.
+     *
+     * @metadata macro
+     */
+    registerProvider<T>(providerConfig: ProviderConfig, injectionId?: GenericId<T>): this;
+    /**
+     * Register a new class provider.
+     *
+     * This is just a shorthand for `registerProvider` which uses the generated `identifier` from the class.
+     */
+    registerClassProvider(provider: Constructor, options?: ProviderRegistrationOptions): this;
+    /**
+     * An easy way to apply a function to the builder without breaking chaining.
+     */
+    apply(callback: (builder: ModuleBuilder) => ModuleBuilder): ModuleBuilder;
+    /**
+     * Finalizes this module.
+     */
+    build(): ModuleDefinition;
+    /**
+     * Ignites this module.
+     *
+     * This is shorthand for `.build().ignite(options)`
+     */
+    ignite(options?: IgniteOptions): import("./module").Module;
+}
+export {};

package/out/module/moduleBuilder.luau

@@ -0,0 +1,169 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local ModuleDefinition = TS.import(script, script.Parent, "moduleDefinition").ModuleDefinition
+local getClassesInPath = TS.import(script, script.Parent.Parent, "utility", "getClassesInPath").getClassesInPath
+local getClassesInGlob = TS.import(script, script.Parent.Parent, "utility", "globs").getClassesInGlob
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local LIFECYCLE_SLOT = TS.import(script, script.Parent.Parent, "plugin", "pluginDefinition").LIFECYCLE_SLOT
+local _providerRegistration = TS.import(script, script.Parent, "providerRegistration")
+local getProviderClassId = _providerRegistration.getProviderClassId
+local normalizeProviderConfig = _providerRegistration.normalizeProviderConfig
+local ModuleBuilder
+do
+	ModuleBuilder = setmetatable({}, {
+		__tostring = function()
+			return "ModuleBuilder"
+		end,
+	})
+	ModuleBuilder.__index = ModuleBuilder
+	function ModuleBuilder.new(...)
+		local self = setmetatable({}, ModuleBuilder)
+		return self:constructor(...) or self
+	end
+	function ModuleBuilder:constructor()
+		local _original = ModuleBuilder.moduleCount
+		ModuleBuilder.moduleCount += 1
+		self.moduleIndex = _original
+		self.module = {
+			debugName = "Anonymous",
+			providers = {},
+			plugins = {},
+		}
+	end
+	function ModuleBuilder:includePlugin(plugin, options)
+		local plugins = self.module.plugins
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(v)
+			return v.plugin == plugin
+		end
+		for _k, _v in plugins do
+			if _callback(_v, _k - 1, plugins) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		if _result then
+			return self
+		end
+		-- A slotted plugin takes the place of whatever holds its slot -- the default lifecycle
+		-- plugin, usually -- rather than joining it, and keeps that position so hook order is stable.
+		local _result_1
+		if plugin.slot ~= nil then
+			-- ▼ ReadonlyArray.findIndex ▼
+			local _callback_1 = function(v)
+				return v.plugin.slot == plugin.slot
+			end
+			local _result_2 = -1
+			for _i, _v in plugins do
+				if _callback_1(_v, _i - 1, plugins) == true then
+					_result_2 = _i - 1
+					break
+				end
+			end
+			-- ▲ ReadonlyArray.findIndex ▲
+			_result_1 = _result_2
+		else
+			_result_1 = -1
+		end
+		local occupant = _result_1
+		local inclusion = {
+			plugin = plugin,
+			scope = options,
+		}
+		if occupant ~= -1 then
+			plugins[occupant + 1] = inclusion
+		else
+			table.insert(plugins, inclusion)
+		end
+		return self
+	end
+	function ModuleBuilder:disableDefaultLifecycle()
+		local plugins = self.module.plugins
+		for i = #plugins - 1, 0, -1 do
+			if plugins[i + 1].plugin.slot == LIFECYCLE_SLOT then
+				local _i = i
+				table.remove(plugins, _i + 1)
+			end
+		end
+		return self
+	end
+	function ModuleBuilder:setDebugName(debugNameOrLevel)
+		local _debugNameOrLevel = debugNameOrLevel
+		if type(_debugNameOrLevel) == "string" then
+			self.module.debugName = debugNameOrLevel
+		else
+			local source, line = debug.info(debugNameOrLevel + 1, "sl")
+			local _exp = self.moduleIndex
+			local _condition = (string.match(source, "(%w+)$"))
+			if _condition == nil then
+				_condition = source
+			end
+			self.module.debugName = `{_exp}+{_condition}:{line}`
+		end
+		return self
+	end
+	function ModuleBuilder:registerProviders(_stringPath, options, path)
+		local _path = path
+		assert(_path)
+		return self:registerProviderClasses(getClassesInPath(path), options)
+	end
+	function ModuleBuilder:registerProvidersGlob(_glob, options, glob)
+		local _arg0 = glob ~= nil
+		assert(_arg0)
+		return self:registerProviderClasses(getClassesInGlob(glob), options)
+	end
+	function ModuleBuilder:registerProviderClasses(classes, options)
+		for _, provider in classes do
+			if Reflect.hasOwnMetadata(provider, "flamework:provider") then
+				self:registerClassProvider(provider, options)
+			end
+		end
+		return self
+	end
+	function ModuleBuilder:registerProvider(providerConfig, injectionId)
+		local _arg0 = injectionId ~= nil
+		assert(_arg0)
+		local _providers = self.module.providers
+		local _arg0_1 = {
+			config = normalizeProviderConfig(providerConfig),
+			injectionId = injectionId,
+		}
+		table.insert(_providers, _arg0_1)
+		return self
+	end
+	function ModuleBuilder:registerClassProvider(provider, options)
+		local _result
+		if options ~= nil then
+			local _object = {
+				type = "class",
+				value = provider,
+			}
+			for _k, _v in options do
+				_object[_k] = _v
+			end
+			_result = _object
+		else
+			_result = {
+				type = "class",
+				value = provider,
+			}
+		end
+		local config = _result
+		return self:registerProvider(config, getProviderClassId(provider))
+	end
+	function ModuleBuilder:apply(callback)
+		return callback(self)
+	end
+	function ModuleBuilder:build()
+		return ModuleDefinition.new(self.module)
+	end
+	function ModuleBuilder:ignite(options)
+		return self:build():ignite(options)
+	end
+	ModuleBuilder.moduleCount = 0
+end
+return {
+	ModuleBuilder = ModuleBuilder,
+}

package/out/module/moduleDefinition.d.ts

@@ -0,0 +1,105 @@
+import type { Modding } from "../modding";
+import type { PluginDefinition } from "../plugin/pluginDefinition";
+import { type Module } from "./module";
+import type { ScopeCondition } from "./scopes";
+/**
+ * Options for one ignition of a module.
+ *
+ * `activeIn` and `inactiveIn` are the module's own scope condition. It applies to every provider
+ * and component the module registers, on top of the registration's and the class's own conditions.
+ * A module whose condition does not hold still ignites, holding nothing.
+ */
+export interface IgniteOptions extends ScopeCondition {
+    /**
+     * Makes this module the one `Dependency<T>()` resolves against, replacing the current default.
+     *
+     * The first root module ignited in a realm becomes the default on its own, so a game never needs
+     * this. Pass it where a realm ignites more than one root -- tests, tools -- and a later one is the
+     * one `Dependency<T>()` should answer from.
+     */
+    default?: boolean;
+    /**
+     * Modules whose providers this one can inject and resolve, searched in order after its own,
+     * each through its own imports. Every one has to be ignited already.
+     *
+     * An import keeps its providers: their lifecycle, observers and extinguish stay with it, and
+     * this module only resolves them. An own registration of a class an import already resolves to
+     * is dropped in favour of the import's instance, unless it is `isolated`; a different class
+     * under the same id is kept, which is how a fake stands in for an import's provider here.
+     * Extinguishing an import extinguishes this module first.
+     */
+    imports?: readonly Module[];
+}
+/** How a plugin was included: the plugin, and the condition its inclusion was given. */
+export interface PluginInclusion {
+    readonly plugin: PluginDefinition;
+    /** The plugin is set up only while this holds; without one it always is. */
+    readonly scope?: ScopeCondition;
+}
+/** The configuration of the module. */
+export interface ModuleState {
+    /** The debug name of this module. */
+    readonly debugName: string;
+    /** Contains all the included providers, as well as their configuration. */
+    readonly providers: readonly ModuleProvider[];
+    /** The plugins to set up on ignition, in inclusion order. */
+    readonly plugins: readonly PluginInclusion[];
+}
+export declare class ModuleDefinition {
+    private moduleState;
+    constructor(moduleState: ModuleState);
+    ignite(options?: IgniteOptions): Module;
+}
+export type ModuleProvider = {
+    config: ProviderConfig;
+    injectionId: string;
+};
+/**
+ * What a registration can say about itself, whichever form it takes: an option on the class and
+ * path registrations, or written on the config of `registerProvider`.
+ */
+export interface ProviderRegistrationOptions extends ScopeCondition {
+    /**
+     * Keeps an own instance of a class that an imported module already holds. Without it, an own
+     * registration of the same class as one an import resolves to is dropped, and the import's
+     * instance answers. Class providers only.
+     */
+    isolated?: boolean;
+}
+export type ProviderConfig = ProviderRegistrationOptions & ({
+    type: "class";
+    value: object;
+    /**
+     * A lazy class provider is not constructed during ignition. It is constructed the first
+     * time something resolves it, and is otherwise never created.
+     *
+     * Defaults to the `lazy` option of the class's `@Provider()` decorator, or `false`.
+     */
+    lazy?: boolean;
+} | {
+    type: "alias";
+    injectionId: string;
+} | {
+    type: "function";
+    callback: (context: InjectionContext) => unknown;
+});
+export type InjectionContext = {
+    /**
+     * This is the ID of the dependency being requested.
+     */
+    injectionId: string;
+    /**
+     * This is the dependency info for the requested dependency.
+     */
+    dependencyInfo: Modding.DependencyInfo;
+    /**
+     * The module resolving the dependency, which is the one the provider is registered in.
+     */
+    module: Module;
+    /**
+     * This is the class requesting the dependency.
+     *
+     * This can be used to retrieve information about the original class, such as the class name for a logging dependency.
+     */
+    origin?: object;
+};

package/out/module/moduleDefinition.luau

@@ -0,0 +1,79 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _defaultModule = TS.import(script, script.Parent, "defaultModule")
+local clearDefaultModule = _defaultModule.clearDefaultModule
+local getDefaultModule = _defaultModule.getDefaultModule
+local setDefaultModule = _defaultModule.setDefaultModule
+local createModuleInstantiation = TS.import(script, script.Parent, "module").createModuleInstantiation
+--[[
+	*
+	 * Options for one ignition of a module.
+	 *
+	 * `activeIn` and `inactiveIn` are the module's own scope condition. It applies to every provider
+	 * and component the module registers, on top of the registration's and the class's own conditions.
+	 * A module whose condition does not hold still ignites, holding nothing.
+	 
+]]
+--* How a plugin was included: the plugin, and the condition its inclusion was given. 
+--* The configuration of the module. 
+local ModuleDefinition
+do
+	ModuleDefinition = setmetatable({}, {
+		__tostring = function()
+			return "ModuleDefinition"
+		end,
+	})
+	ModuleDefinition.__index = ModuleDefinition
+	function ModuleDefinition.new(...)
+		local self = setmetatable({}, ModuleDefinition)
+		return self:constructor(...) or self
+	end
+	function ModuleDefinition:constructor(moduleState)
+		self.moduleState = moduleState
+	end
+	function ModuleDefinition:ignite(options)
+		local module = createModuleInstantiation(self.moduleState, options)
+		-- Claimed before ignition rather than after it, so that `Dependency<T>()` answers inside a
+		-- provider constructor, as it did in v1.
+		local previous = getDefaultModule()
+		local _result = options
+		if _result ~= nil then
+			_result = _result.default
+		end
+		local _condition = _result == true
+		if not _condition then
+			_condition = previous == nil
+		end
+		local claimsDefault = _condition
+		if claimsDefault then
+			setDefaultModule(module)
+		end
+		local _exitType, _returns = TS.try(function()
+			return TS.TRY_RETURN, { module.ignite() }
+		end, function(err)
+			-- A module that failed to ignite must not stay the default: the next root ignited would
+			-- never claim it, and `Dependency<T>()` would keep answering from the wreck. The root it
+			-- replaced is put back, if it is still ignited, so that a failed ignition leaves the
+			-- default as it found it.
+			if claimsDefault then
+				clearDefaultModule(module)
+				if previous ~= nil and previous.isIgnited() and getDefaultModule() == nil then
+					setDefaultModule(previous)
+				end
+			end
+			error(err, 0)
+		end)
+		if _exitType then
+			return unpack(_returns)
+		end
+	end
+end
+--[[
+	*
+	 * What a registration can say about itself, whichever form it takes: an option on the class and
+	 * path registrations, or written on the config of `registerProvider`.
+	 
+]]
+return {
+	ModuleDefinition = ModuleDefinition,
+}

package/out/module/moduleHooks.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Conventional priorities for {@link HookOptions.priority}.
+ *
+ * Any number is accepted; these exist so that plugins can order themselves against each other
+ * without agreeing on magic numbers.
+ */
+export declare const HookPriority: {
+    /** Runs before hooks that did not specify a priority. */
+    readonly First: -1000;
+    /** The default. */
+    readonly Normal: 0;
+    /** Runs after hooks that did not specify a priority. */
+    readonly Last: 1000;
+};
+export interface HookOptions {
+    /**
+     * Orders this hook against the other hooks of the same phase on the same module.
+     *
+     * Lower values run first, and hooks with an equal priority run in registration order.
+     * Defaults to {@link HookPriority.Normal}.
+     */
+    priority?: number;
+}

package/out/module/moduleHooks.luau

@@ -0,0 +1,19 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Conventional priorities for {@link HookOptions.priority}.
+	 *
+	 * Any number is accepted; these exist so that plugins can order themselves against each other
+	 * without agreeing on magic numbers.
+	 
+]]
+local HookPriority = {
+	First = -1000,
+	Normal = 0,
+	Last = 1000,
+}
+--* @internal 
+--* @internal 
+return {
+	HookPriority = HookPriority,
+}

package/out/module/providerRegistration.d.ts

@@ -0,0 +1,22 @@
+import type { Constructor } from "../utility/constructors";
+import type { ProviderConfig } from "./moduleDefinition";
+import { type ScopeCondition } from "./scopes";
+/**
+ * Metadata is inherited through the class hierarchy, so this deliberately checks the class's own
+ * metadata: an undecorated subclass of a provider carries the parent's identifier, and registering
+ * it would register it under the parent's id.
+ */
+export declare function assertIsProviderClass(value: object): void;
+/** The generated identifier a provider class is registered under. */
+export declare function getProviderClassId(provider: Constructor): string;
+/**
+ * Checks that a class provider carries `@Provider()`, and fills in `lazy` from the decorator when
+ * the registration did not say. Other kinds of provider are returned as they are.
+ */
+export declare function normalizeProviderConfig(config: ProviderConfig): ProviderConfig;
+/**
+ * The scope condition a provider's own decorator set, when it is a class provider with one, and
+ * no condition otherwise. Own metadata, as everywhere else: a subclass does not inherit its
+ * parent's scope.
+ */
+export declare function getProviderClassScope(config: ProviderConfig): ScopeCondition;

package/out/module/providerRegistration.luau

@@ -0,0 +1,80 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Reflect = TS.import(script, script.Parent.Parent, "reflect").Reflect
+local NO_CONDITION = TS.import(script, script.Parent, "scopes").NO_CONDITION
+--[[
+	*
+	 * Metadata is inherited through the class hierarchy, so this deliberately checks the class's own
+	 * metadata: an undecorated subclass of a provider carries the parent's identifier, and registering
+	 * it would register it under the parent's id.
+	 
+]]
+local function assertIsProviderClass(value)
+	if Reflect.hasOwnMetadata(value, "flamework:provider") then
+		return nil
+	end
+	if Reflect.hasMetadata(value, "flamework:provider") then
+		error(`class '{value}' is missing the @Provider() decorator: it inherits one from a parent class, but every provider must be decorated itself`)
+	end
+	error(`class '{value}' is missing the @Provider() decorator`)
+end
+--* The generated identifier a provider class is registered under. 
+local function getProviderClassId(provider)
+	assertIsProviderClass(provider)
+	local providerId = Reflect.getOwnMetadata(provider, "identifier")
+	local _arg0 = providerId ~= nil
+	local _arg1 = `class '{provider}' has no identifier, was it compiled with the Flamework transformer?`
+	assert(_arg0, _arg1)
+	return providerId
+end
+--[[
+	*
+	 * Checks that a class provider carries `@Provider()`, and fills in `lazy` from the decorator when
+	 * the registration did not say. Other kinds of provider are returned as they are.
+	 
+]]
+local function normalizeProviderConfig(config)
+	if config.type ~= "class" then
+		return config
+	end
+	assertIsProviderClass(config.value)
+	if config.lazy ~= nil then
+		return config
+	end
+	local decoratorConfig = Reflect.getOwnMetadata(config.value, "flamework:providerConfig")
+	local _object = table.clone(config)
+	setmetatable(_object, nil)
+	local _left = "lazy"
+	local _result = decoratorConfig
+	if _result ~= nil then
+		_result = _result.lazy
+	end
+	_object[_left] = _result == true
+	return _object
+end
+--[[
+	*
+	 * The scope condition a provider's own decorator set, when it is a class provider with one, and
+	 * no condition otherwise. Own metadata, as everywhere else: a subclass does not inherit its
+	 * parent's scope.
+	 
+]]
+local function getProviderClassScope(config)
+	if config.type ~= "class" then
+		return NO_CONDITION
+	end
+	local decoratorConfig = Reflect.getOwnMetadata(config.value, "flamework:providerConfig")
+	if decoratorConfig == nil then
+		return NO_CONDITION
+	end
+	return {
+		activeIn = decoratorConfig.activeIn,
+		inactiveIn = decoratorConfig.inactiveIn,
+	}
+end
+return {
+	assertIsProviderClass = assertIsProviderClass,
+	getProviderClassId = getProviderClassId,
+	normalizeProviderConfig = normalizeProviderConfig,
+	getProviderClassScope = getProviderClassScope,
+}

package/out/module/scopes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * When something is registered, in terms of the build's active scopes.
+ *
+ * A condition holds when `activeIn` is empty or names an active scope, and `inactiveIn` names
+ * none. Conditions combine by AND: a class is registered only when the module's condition, its
+ * registration's and its own all hold, so a class can narrow the module's condition and never
+ * widen it.
+ */
+export interface ScopeCondition {
+    /**
+     * Registered only while at least one of these scopes is active. Empty or absent means no
+     * requirement.
+     */
+    activeIn?: readonly string[];
+    /** Never registered while any of these scopes is active. */
+    inactiveIn?: readonly string[];
+}
+/**
+ * The scopes this build is compiled with, as written in `flamework.config.json` (usually from
+ * the environment). `"*"` in the list stands for every scope.
+ */
+export declare function getActiveScopes(): readonly string[];
+/** Whether a scope is active in this build. */
+export declare function isScopeActive(scope: string): boolean;
+/**
+ * The condition of something that was not given one. Lists of conditions hold this rather than
+ * `undefined`: an array with a hole in it is not an array Luau can measure or walk.
+ */
+export declare const NO_CONDITION: ScopeCondition;
+/** Whether a condition holds against the active scopes. No condition always holds. */
+export declare function holdsCondition(condition: ScopeCondition | undefined): boolean;
+/** Whether every condition holds. */
+export declare function holdsEveryCondition(conditions: ReadonlyArray<ScopeCondition>): boolean;
+/** Whether a condition asks for anything at all, so that a message can leave the empty ones out. */
+export declare function hasCondition(condition: ScopeCondition | undefined): condition is ScopeCondition;
+/**
+ * Describes the conditions that applied to something, and the active set they were judged
+ * against, for an error message: `activeIn [a, b]; inactiveIn [c]; active scopes [a]`.
+ */
+export declare function describeConditions(conditions: ReadonlyArray<ScopeCondition>): string;