@flamework-experimental/core 2.0.0-alpha.0

package/out/module/scopes.luau

@@ -0,0 +1,159 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local getRuntimeConfig = TS.import(script, script.Parent.Parent, "utility", "runtimeConfig").getRuntimeConfig
+--[[
+	*
+	 * 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.
+	 
+]]
+local configured
+local override
+local function getConfiguredScopes()
+	if override ~= nil then
+		return override
+	end
+	if configured == nil then
+		local _result = getRuntimeConfig().scopes
+		if _result ~= nil then
+			_result = _result.active
+		end
+		local _condition = _result
+		if _condition == nil then
+			_condition = {}
+		end
+		configured = _condition
+	end
+	return configured
+end
+--[[
+	*
+	 * The scopes this build is compiled with, as written in `flamework.config.json` (usually from
+	 * the environment). `"*"` in the list stands for every scope.
+	 
+]]
+local function getActiveScopes()
+	return getConfiguredScopes()
+end
+--* Whether a scope is active in this build. 
+local function isScopeActive(scope)
+	local active = getConfiguredScopes()
+	local _condition = table.find(active, "*") ~= nil
+	if not _condition then
+		local _scope = scope
+		_condition = table.find(active, _scope) ~= nil
+	end
+	return _condition
+end
+--[[
+	*
+	 * 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.
+	 
+]]
+local NO_CONDITION = {}
+--* Whether a condition holds against the active scopes. No condition always holds. 
+local function holdsCondition(condition)
+	if condition == nil then
+		return true
+	end
+	local _condition = condition.inactiveIn ~= nil
+	if _condition then
+		local _exp = condition.inactiveIn
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		for _k, _v in _exp do
+			if isScopeActive(_v, _k - 1, _exp) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		_condition = _result
+	end
+	if _condition then
+		return false
+	end
+	local _condition_1 = condition.activeIn ~= nil and #condition.activeIn > 0
+	if _condition_1 then
+		local _exp = condition.activeIn
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		for _k, _v in _exp do
+			if isScopeActive(_v, _k - 1, _exp) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		_condition_1 = not _result
+	end
+	if _condition_1 then
+		return false
+	end
+	return true
+end
+--* Whether every condition holds. 
+local function holdsEveryCondition(conditions)
+	for _, condition in conditions do
+		if not holdsCondition(condition) then
+			return false
+		end
+	end
+	return true
+end
+--* Whether a condition asks for anything at all, so that a message can leave the empty ones out. 
+local function hasCondition(condition)
+	return condition ~= nil and ((condition.activeIn ~= nil and #condition.activeIn > 0) or (condition.inactiveIn ~= nil and #condition.inactiveIn > 0))
+end
+--[[
+	*
+	 * 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]`.
+	 
+]]
+local function describeConditions(conditions)
+	local parts = {}
+	for _, condition in conditions do
+		if not hasCondition(condition) then
+			continue
+		end
+		if condition.activeIn ~= nil and #condition.activeIn > 0 then
+			local _arg0 = `activeIn [{table.concat(condition.activeIn, ", ")}]`
+			table.insert(parts, _arg0)
+		end
+		if condition.inactiveIn ~= nil and #condition.inactiveIn > 0 then
+			local _arg0 = `inactiveIn [{table.concat(condition.inactiveIn, ", ")}]`
+			table.insert(parts, _arg0)
+		end
+	end
+	local _arg0 = `active scopes [{table.concat(getConfiguredScopes(), ", ")}]`
+	table.insert(parts, _arg0)
+	return table.concat(parts, "; ")
+end
+--[[
+	*
+	 * Replaces the active scopes for the rest of the run, or restores the configured ones with
+	 * `undefined`. For the test harness, which has no `config.json`; a game's scopes are what it was
+	 * compiled with.
+	 *
+	 * @internal
+	 
+]]
+local function __setActiveScopes(scopes)
+	override = scopes
+end
+return {
+	getActiveScopes = getActiveScopes,
+	isScopeActive = isScopeActive,
+	holdsCondition = holdsCondition,
+	holdsEveryCondition = holdsEveryCondition,
+	hasCondition = hasCondition,
+	describeConditions = describeConditions,
+	__setActiveScopes = __setActiveScopes,
+	NO_CONDITION = NO_CONDITION,
+}

package/out/plugin/pluginDefinition.d.ts

@@ -0,0 +1,128 @@
+import type { Modding } from "../modding";
+import type { Module } from "../module/module";
+import type { ProviderConfig, ProviderRegistrationOptions } from "../module/moduleDefinition";
+import type { HookOptions } from "../module/moduleHooks";
+import type { ScopeCondition } from "../module/scopes";
+import type { Constructor } from "../utility/constructors";
+export declare class PluginDefinition {
+    /** Names the plugin in error messages. */
+    readonly name: string;
+    constructor(
+    /** Names the plugin in error messages. */
+    name: string, 
+    /** @internal */
+    setup: (target: PluginTarget) => void, 
+    /**
+     * A slot at most one plugin fills per module. On the builder, including a plugin whose slot
+     * is taken replaces the plugin in it; at ignition, a second plugin for a filled slot is
+     * refused. Two lifecycle plugins would tick everything twice, which is what this prevents.
+     *
+     * @internal
+     */
+    slot?: string | undefined);
+}
+/**
+ * What a plugin's setup is handed: the module the plugin is being included in, and the ways a
+ * plugin can act on it. Everything here registers into that module.
+ *
+ * These are function-typed properties rather than methods, as on `Module`: roblox-ts tells the two
+ * apart, and the implementation is a table of closures with no `this`.
+ */
+export interface PluginTarget {
+    /**
+     * The module being set up. It has not ignited, so nothing can be resolved from it yet; hold it
+     * for the hooks, which run once it can.
+     */
+    readonly module: Module;
+    /**
+     * The module's own scope condition, from `ignite`, when it has one. Everything the module
+     * registers is subject to it; {@link isActive} folds it in, so this is for messages.
+     */
+    readonly scope?: ScopeCondition;
+    /**
+     * Whether something with these conditions is registered in this module: the module's own
+     * condition and every one given must hold. A plugin that keeps a registry of its own -- the
+     * components plugin, say -- asks this for each class, so that its classes are scoped the way the
+     * module's providers are.
+     */
+    isActive: (...conditions: ScopeCondition[]) => boolean;
+    /**
+     * Registers a class provider in the module, constructed with dependency injection during
+     * ignition like any provider the module registered itself.
+     */
+    registerClassProvider: (provider: Constructor, options?: ProviderRegistrationOptions) => void;
+    /**
+     * Registers every exported `@Provider()` class under a source folder, as the module builder's
+     * `registerProviders` does. This is how a plugin ships a folder of providers. The options apply
+     * to every class found.
+     *
+     * @metadata macro
+     */
+    registerProviders: <T extends string>(path: T, options?: ProviderRegistrationOptions, resolved?: Modding.Intrinsic<"path", [T], string[]>) => void;
+    /**
+     * Registers every exported `@Provider()` class under every folder a compile-time glob matches.
+     *
+     * @metadata macro
+     */
+    registerProvidersGlob: <T extends string>(glob: T, options?: ProviderRegistrationOptions, resolved?: Modding.Intrinsic<"pathglob", [T], string>) => void;
+    /**
+     * Registers a class, function or alias provider in the module.
+     *
+     * @metadata macro
+     */
+    registerProvider: <T>(config: ProviderConfig, id?: string | Modding.Target.Id<T>) => void;
+    /**
+     * Provides a ready-made object under its type's id, so that the module's providers can inject it
+     * and `resolveDependency` finds it. This is how a plugin hands the module the thing it built.
+     *
+     * The object joins the interfaces it implements once every plugin has been set up, and leaves
+     * them when the module extinguishes, like a provider the module constructed.
+     *
+     * @metadata macro
+     */
+    provideInstance: <T extends object>(instance: T, id?: string | Modding.Target.Id<T>) => void;
+    /**
+     * Includes another plugin in the module, set up now, before this one continues. A plugin reached
+     * more than once in one ignition -- included by the module and by a plugin, or by two plugins --
+     * is set up once. With a scope condition that does not hold, the inclusion is skipped.
+     */
+    includePlugin: (plugin: PluginDefinition, options?: ScopeCondition) => void;
+    /**
+     * Runs before the module's providers are constructed. Nothing can be resolved yet; this is where
+     * a plugin registers state that providers will look at while being constructed.
+     */
+    onPreIgnite: (callback: (module: Module) => void, options?: HookOptions) => void;
+    /** Runs after every provider has been constructed. */
+    onPostIgnite: (callback: (module: Module) => void, options?: HookOptions) => void;
+    /** Runs when the module extinguishes, before its providers are released. */
+    onExtinguished: (callback: (module: Module) => void, options?: HookOptions) => void;
+    /**
+     * Observes every object in the module that implements `T`: providers as they are constructed,
+     * and anything attached through `createClassInstance` or `listen`. Matching is structural, from
+     * the `implements` clause the transformer recorded, so the class needs a Flamework decorator.
+     *
+     * @metadata macro
+     */
+    observe: <T>(config: InterfaceConfiguration<T>, id?: string | Modding.Target.Id<T>) => void;
+}
+export interface InterfaceConfiguration<T> {
+    /** Invoked when an object implementing the interface is constructed or attached. */
+    onAdded?: (value: T, context: InterfaceContext) => void;
+    /** Invoked when an object implementing the interface is released, or its module extinguishes. */
+    onRemoved?: (value: T, context: InterfaceContext) => void;
+}
+/**
+ * What kind of object an observer is being told about.
+ *
+ * - `provider`: a provider the module constructed, during ignition or lazily, or one a plugin
+ *   provided.
+ * - `instance`: an object attached through `createClassInstance` or `listen`, which is owned by
+ *   whoever created it (for example, a component owned by `Components`).
+ */
+export type InterfaceTargetKind = "provider" | "instance";
+export interface InterfaceContext {
+    /** The id of the interface being observed. */
+    interfaceId: string;
+    /** Whether the object is a provider of the module, or an instance attached to it. */
+    kind: InterfaceTargetKind;
+}

package/out/plugin/pluginDefinition.luau

@@ -0,0 +1,61 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * A plugin: a name, and a setup function run once per ignition of every module that includes it.
+	 *
+	 * The setup is handed the module being ignited, before any of its providers exist, and registers
+	 * whatever the plugin adds to it -- providers, hooks, observers, other plugins. State the setup
+	 * creates belongs to that one ignition: a plugin included by two modules, or by one definition
+	 * ignited twice, is set up separately for each and shares nothing between them unless it closes
+	 * over module-level state on purpose.
+	 
+]]
+--[[
+	*
+	 * The slot the lifecycle plugin fills: every module starts with one, and a module never runs two.
+	 *
+	 * @internal
+	 
+]]
+local LIFECYCLE_SLOT = "lifecycle"
+local PluginDefinition
+do
+	PluginDefinition = setmetatable({}, {
+		__tostring = function()
+			return "PluginDefinition"
+		end,
+	})
+	PluginDefinition.__index = PluginDefinition
+	function PluginDefinition.new(...)
+		local self = setmetatable({}, PluginDefinition)
+		return self:constructor(...) or self
+	end
+	function PluginDefinition:constructor(name, setup, slot)
+		self.name = name
+		self.setup = setup
+		self.slot = slot
+	end
+end
+--[[
+	*
+	 * What a plugin's setup is handed: the module the plugin is being included in, and the ways a
+	 * plugin can act on it. Everything here registers into that module.
+	 *
+	 * These are function-typed properties rather than methods, as on `Module`: roblox-ts tells the two
+	 * apart, and the implementation is a table of closures with no `this`.
+	 
+]]
+--[[
+	*
+	 * What kind of object an observer is being told about.
+	 *
+	 * - `provider`: a provider the module constructed, during ignition or lazily, or one a plugin
+	 *   provided.
+	 * - `instance`: an object attached through `createClassInstance` or `listen`, which is owned by
+	 *   whoever created it (for example, a component owned by `Components`).
+	 
+]]
+return {
+	LIFECYCLE_SLOT = LIFECYCLE_SLOT,
+	PluginDefinition = PluginDefinition,
+}

package/out/prelude.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exports `t` so that generated guards can import it through `@flamework-experimental/core/out/prelude`.
+ *
+ * The transformer does this when the consuming project resolves a different `@rbxts/t` than core
+ * does, so that guards always run against the version core was built and tested with.
+ */
+import { t } from "@rbxts/t";
+export { t };

package/out/prelude.luau

@@ -0,0 +1,14 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+--[[
+	*
+	 * Re-exports `t` so that generated guards can import it through `@flamework-experimental/core/out/prelude`.
+	 *
+	 * The transformer does this when the consuming project resolves a different `@rbxts/t` than core
+	 * does, so that guards always run against the version core was built and tested with.
+	 
+]]
+local t = TS.import(script, TS.getModule(script, "@rbxts", "t").lib.ts).t
+return {
+	t = t,
+}

package/out/provider.d.ts

@@ -0,0 +1,27 @@
+import type { ScopeCondition } from "./module/scopes";
+export interface ProviderDecoratorConfig extends ScopeCondition {
+    /**
+     * A lazy provider is not constructed during ignition. It is constructed the first time something
+     * resolves it -- a constructor parameter, `resolveDependency`, or `createClassInstance` -- and is
+     * otherwise never created.
+     *
+     * This is the v2 equivalent of v1's `@Optional()`. A lazy provider first resolved after ignition
+     * still receives `onInit` and `onStart` from the lifecycle plugin, at the moment it is constructed.
+     *
+     * Defaults to `false`.
+     */
+    lazy?: boolean;
+}
+/**
+ * Register a class as a provider.
+ *
+ * Unlike Flamework v1's `@Service` and `@Controller`, a provider is not bound to a realm. Which
+ * providers exist on which realm is decided by the module that registers them, so this metadata
+ * must be defined on both the client and the server.
+ *
+ * `activeIn` and `inactiveIn` scope the class: it is registered only when they hold against the
+ * build's active scopes, on top of whatever condition the module and the registration set.
+ *
+ * @metadata reflect identifier flamework:dependencies flamework:implements flamework:parameters injectable
+ */
+export declare function Provider(config?: ProviderDecoratorConfig): (constructor: object) => void;

package/out/provider.luau

@@ -0,0 +1,26 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Reflect = TS.import(script, script.Parent, "reflect").Reflect
+--[[
+	*
+	 * Register a class as a provider.
+	 *
+	 * Unlike Flamework v1's `@Service` and `@Controller`, a provider is not bound to a realm. Which
+	 * providers exist on which realm is decided by the module that registers them, so this metadata
+	 * must be defined on both the client and the server.
+	 *
+	 * `activeIn` and `inactiveIn` scope the class: it is registered only when they hold against the
+	 * build's active scopes, on top of whatever condition the module and the registration set.
+	 *
+	 * @metadata reflect identifier flamework:dependencies flamework:implements flamework:parameters injectable
+	 
+]]
+local function Provider(config)
+	return function(constructor)
+		Reflect.defineMetadata(constructor, "flamework:provider", true)
+		Reflect.defineMetadata(constructor, "flamework:providerConfig", config or {})
+	end
+end
+return {
+	Provider = Provider,
+}

package/out/reflect.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Reflection/metadata API
+ */
+export declare namespace Reflect {
+    /**
+     * Apply metadata onto this object.
+     */
+    function defineMetadata(obj: object, key: string, value: unknown, property?: string): void;
+    /**
+     * Apply metadata in batch onto this object.
+     */
+    function defineMetadataBatch(obj: object, list: {
+        [key: string]: unknown;
+    }, property?: string): void;
+    /**
+     * Delete metadata from this object.
+     */
+    function deleteMetadata(obj: object, key: string, property?: string): void;
+    /**
+     * Get metadata from this object.
+     * Type parameter is an assertion.
+     */
+    function getOwnMetadata<T>(obj: object, key: string, property?: string): T | undefined;
+    /**
+     * Check if this object has the specified metadata key.
+     */
+    function hasOwnMetadata(obj: object, key: string, property?: string): boolean;
+    /**
+     * Retrieve all metadata keys for this object.
+     */
+    function getOwnMetadataKeys(obj: object, property?: string): string[];
+    /**
+     * Retrieves all properties (that contain metadata) on this object.
+     */
+    function getOwnProperties(obj: object): string[];
+    /**
+     * Retrieve all values for the specified key from the object and its parents.
+     * Type parameter is an assertion.
+     */
+    function getMetadatas<T extends defined>(obj: object, key: string, property?: string): T[];
+    /**
+     * Get metadata from this object or its parents.
+     * Type parameter is an assertion.
+     */
+    function getMetadata<T>(obj: object, key: string, property?: string): T | undefined;
+    /**
+     * Check if this object or any of its parents has the specified metadata key.
+     */
+    function hasMetadata(obj: object, key: string, property?: string): boolean;
+    /**
+     * Retrieve all metadata keys for this object and its parents.
+     */
+    function getMetadataKeys(obj: object, property?: string): string[];
+    /**
+     * Retrieves all properties (that contain metadata) on this object and its parents.
+     */
+    function getProperties(obj: object): string[];
+    /** @hidden Internal use, do not use */
+    function resetObject(object: object): void;
+}