@flamework-experimental/core 2.0.0-alpha.0

package/out/utility/metadata.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the `include/flamework` folder that holds a metadata module written by the transformer
+ * (`include/flamework/<name>.json`), by walking up from this script until a `flamework` folder
+ * with the requested child is found. The include directory is an ancestor of every Flamework
+ * package in a roblox-ts project, which is what makes this work.
+ */
+export declare function findMetadataFolder(name: string): Instance | undefined;
+/**
+ * Finds and requires a metadata module written by the transformer; Rojo turns the JSON file into a
+ * ModuleScript returning its table.
+ */
+export declare function findMetadataContainer<T>(name: string): T | undefined;

package/out/utility/metadata.luau

@@ -0,0 +1,43 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Finds the `include/flamework` folder that holds a metadata module written by the transformer
+	 * (`include/flamework/<name>.json`), by walking up from this script until a `flamework` folder
+	 * with the requested child is found. The include directory is an ancestor of every Flamework
+	 * package in a roblox-ts project, which is what makes this work.
+	 
+]]
+local function findMetadataFolder(name)
+	-- Outside a real place (the Lune harness) `script` is a plain table: there is no tree to walk.
+	if not (typeof(script) == "Instance") then
+		return nil
+	end
+	local current = script
+	while current do
+		local flamework = current:FindFirstChild("flamework")
+		if flamework then
+			local metadata = flamework:FindFirstChild(name)
+			if metadata and metadata:IsA("ModuleScript") then
+				return flamework
+			end
+		end
+		current = current.Parent
+	end
+end
+--[[
+	*
+	 * Finds and requires a metadata module written by the transformer; Rojo turns the JSON file into a
+	 * ModuleScript returning its table.
+	 
+]]
+local function findMetadataContainer(name)
+	local folder = findMetadataFolder(name)
+	if folder == nil then
+		return nil
+	end
+	return require(folder:FindFirstChild(name))
+end
+return {
+	findMetadataFolder = findMetadataFolder,
+	findMetadataContainer = findMetadataContainer,
+}

package/out/utility/pathRoot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The instance every compile-time path is relative to: `game` in a place, and the Rojo tree's own
+ * root in a model or a Studio plugin, whose tree hangs off no service.
+ *
+ * The transformer emits paths relative to the tree's root, and records in `paths.json` how far
+ * below that root the include folder sits; the root is found once by climbing that far from the
+ * folder the metadata was found in. With no metadata -- a package on its own, the test harness --
+ * it is `game`.
+ */
+export declare function getPathRoot(): Instance;
+/**
+ * Walks a compile-time path from {@link getPathRoot}, waiting for each child in turn.
+ *
+ * Under `game` the first segment names a service, and `StarterPlayer/StarterPlayerScripts` is
+ * answered from the local player's `PlayerScripts`, which is where that content actually runs.
+ */
+export declare function resolveRbxPath(rbxPath: readonly string[]): Instance;

package/out/utility/pathRoot.luau

@@ -0,0 +1,105 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
+local Players = _services.Players
+local RunService = _services.RunService
+local StarterPlayer = _services.StarterPlayer
+local _metadata = TS.import(script, script.Parent, "metadata")
+local findMetadataContainer = _metadata.findMetadataContainer
+local findMetadataFolder = _metadata.findMetadataFolder
+--* The shape of `include/flamework/paths.json`, which the transformer writes for game and plugin projects. 
+local cached
+local override
+--[[
+	*
+	 * The instance every compile-time path is relative to: `game` in a place, and the Rojo tree's own
+	 * root in a model or a Studio plugin, whose tree hangs off no service.
+	 *
+	 * The transformer emits paths relative to the tree's root, and records in `paths.json` how far
+	 * below that root the include folder sits; the root is found once by climbing that far from the
+	 * folder the metadata was found in. With no metadata -- a package on its own, the test harness --
+	 * it is `game`.
+	 
+]]
+local function getPathRoot()
+	if override ~= nil then
+		return override
+	end
+	if cached == nil then
+		cached = game
+		local folder = findMetadataFolder("paths")
+		local paths = findMetadataContainer("paths")
+		if folder ~= nil and paths ~= nil then
+			-- The folder is `include/flamework`; its parent is the include folder itself.
+			local node = folder.Parent
+			do
+				local i = 0
+				local _shouldIncrement = false
+				while true do
+					if _shouldIncrement then
+						i += 1
+					else
+						_shouldIncrement = true
+					end
+					if not (i < paths.includeDepth and node ~= nil) then
+						break
+					end
+					node = node.Parent
+				end
+			end
+			if node ~= nil then
+				cached = node
+			end
+		end
+	end
+	return cached
+end
+--[[
+	*
+	 * Walks a compile-time path from {@link getPathRoot}, waiting for each child in turn.
+	 *
+	 * Under `game` the first segment names a service, and `StarterPlayer/StarterPlayerScripts` is
+	 * answered from the local player's `PlayerScripts`, which is where that content actually runs.
+	 
+]]
+local function resolveRbxPath(rbxPath)
+	-- Copied so that a generated path literal is not consumed by this call.
+	local _array = {}
+	local _length = #_array
+	table.move(rbxPath, 1, #rbxPath, _length + 1, _array)
+	local path = _array
+	local node = getPathRoot()
+	if node == game then
+		local serviceName = table.remove(path, 1)
+		local _arg0 = serviceName ~= nil
+		assert(_arg0, "a path under game has to name a service first")
+		node = game:GetService(serviceName)
+		if node == StarterPlayer then
+			local _arg0_1 = table.remove(path, 1) == "StarterPlayerScripts"
+			assert(_arg0_1, "StarterPlayer only supports StarterPlayerScripts")
+			local _arg0_2 = RunService:IsClient()
+			assert(_arg0_2, "The server cannot load StarterPlayer content")
+			node = Players.LocalPlayer:WaitForChild("PlayerScripts")
+		end
+	end
+	for _, segment in path do
+		node = node:WaitForChild(segment)
+	end
+	return node
+end
+--[[
+	*
+	 * Replaces the root paths resolve from, or restores the discovered one with `undefined`. For the
+	 * test harness, which has no tree to discover it in.
+	 *
+	 * @internal
+	 
+]]
+local function __setPathRoot(root)
+	override = root
+end
+return {
+	getPathRoot = getPathRoot,
+	resolveRbxPath = resolveRbxPath,
+	__setPathRoot = __setPathRoot,
+}

package/out/utility/recycleThread.d.ts

@@ -0,0 +1 @@
+export declare function recycleThread(func: () => void): void;

package/out/utility/recycleThread.luau

@@ -0,0 +1,31 @@
+-- Compiled with roblox-ts v3.0.0
+local inactiveThread
+local function reusableThread(func)
+	local thread = coroutine.running()
+	while true do
+		if inactiveThread == thread then
+			inactiveThread = nil
+		end
+		func()
+		-- If there's a different idle thread, we should end the current thread.
+		if inactiveThread ~= nil then
+			break
+		end
+		inactiveThread = thread
+		-- Let go of the callback while idle: it closes over whatever it was run for -- a lifecycle
+		-- listener, a component -- which would otherwise stay reachable from this thread until the
+		-- next callback comes through, and for good when none does.
+		func = nil
+		func = coroutine.yield()
+	end
+end
+local function recycleThread(func)
+	if inactiveThread then
+		task.spawn(inactiveThread, func)
+	else
+		task.spawn(reusableThread, func)
+	end
+end
+return {
+	recycleThread = recycleThread,
+}

package/out/utility/runtimeConfig.d.ts

@@ -0,0 +1,59 @@
+export interface CoreRuntimeConfig {
+    /** Whether lifecycle events are wrapped in `debug.profilebegin`. Defaults to running in Studio. */
+    profiling?: boolean;
+}
+export interface NetworkingRuntimeConfig {
+    /** Whether event and function payloads are serialized. Compiled into the metadata; informational at runtime. */
+    serialization?: boolean;
+}
+export interface ComponentsRuntimeConfig {
+    /** Default `warningTimeout` for components that do not set one. */
+    warningTimeout?: number;
+    /** Default `attributeWarningTimeout` for components that do not set one. */
+    attributeWarningTimeout?: number;
+    /** Default `streamingMode` for components that do not set one. */
+    streamingMode?: "Disabled" | "Watching" | "Contextual";
+}
+export interface ScopesRuntimeConfig {
+    /**
+     * The scopes this build was compiled with, usually taken from the environment at compile time.
+     * `"*"` stands for every scope. Read by the scope checks in `@flamework-experimental/core`.
+     */
+    active?: string[];
+}
+export interface TestingRuntimeConfig {
+    /**
+     * Whether the plugin attaches the host at all. Unset, it follows the scope condition below, so
+     * this is an override for either direction.
+     */
+    enabled?: boolean;
+    /** Scopes under which tests are on: the host attaches when at least one is active. Default `["testing"]`. */
+    activeIn?: readonly string[];
+    /** Scopes under which tests stay off, whatever else is active. */
+    inactiveIn?: readonly string[];
+    /** Runs every test right after ignition, instead of only on request. */
+    autoRun?: boolean;
+    /** Seconds a single test may take before it is cancelled and counted as failed. */
+    timeout?: number;
+    /**
+     * The tree path of a ModuleScript exporting `ignite()`, resolved by the transformer from the
+     * source path in `flamework.config.json`, for runs where nothing starts the game by itself.
+     */
+    entry?: readonly string[];
+}
+/**
+ * The runtime sections of the project's `flamework.config.json`. The transformer writes them to
+ * `include/flamework/config.json` for game projects; a project without them gets an empty object.
+ */
+export interface RuntimeConfig {
+    core?: CoreRuntimeConfig;
+    networking?: NetworkingRuntimeConfig;
+    components?: ComponentsRuntimeConfig;
+    scopes?: ScopesRuntimeConfig;
+    testing?: TestingRuntimeConfig;
+}
+/**
+ * Returns the runtime sections of `flamework.config.json`, read once. Every package takes its
+ * defaults from here, so one file configures the transformer and the runtime alike.
+ */
+export declare function getRuntimeConfig(): RuntimeConfig;

package/out/utility/runtimeConfig.luau

@@ -0,0 +1,25 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local findMetadataContainer = TS.import(script, script.Parent, "metadata").findMetadataContainer
+--[[
+	*
+	 * The runtime sections of the project's `flamework.config.json`. The transformer writes them to
+	 * `include/flamework/config.json` for game projects; a project without them gets an empty object.
+	 
+]]
+local cached
+--[[
+	*
+	 * Returns the runtime sections of `flamework.config.json`, read once. Every package takes its
+	 * defaults from here, so one file configures the transformer and the runtime alike.
+	 
+]]
+local function getRuntimeConfig()
+	if cached == nil then
+		cached = findMetadataContainer("config") or {}
+	end
+	return cached
+end
+return {
+	getRuntimeConfig = getRuntimeConfig,
+}

package/out/utility/tsImport.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This imports the module using the current TS runtime.
+ *
+ * This is necessary when loading packages which must be imported using the RuntimeLib.
+ */
+export declare function tsImport(module: ModuleScript): unknown;

package/out/utility/tsImport.luau

@@ -0,0 +1,15 @@
+-- Compiled with roblox-ts v3.0.0
+local tsImpl = _G[script]
+--[[
+	*
+	 * This imports the module using the current TS runtime.
+	 *
+	 * This is necessary when loading packages which must be imported using the RuntimeLib.
+	 
+]]
+local function tsImport(module)
+	return tsImpl.import(script, module)
+end
+return {
+	tsImport = tsImport,
+}

package/out/utility/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Alias for destructors, which is just a callback.
+ */
+export type Destructor = () => void;
+/**
+ * Checks whether `T` is a union.
+ */
+export type IsUnion<T, U = T> = T extends T ? (U extends T ? false : true) : never;
+/**
+ * Checks whether this interface contains a single field, which is also a Callback.
+ */
+export type HasSingleCallback<T> = [IsUnion<keyof T>, T[keyof T]] extends [false, Callback] ? true : false;
+/**
+ * If this interface contains a single callback, extract its type.
+ */
+export type ExtractSingleCallback<T> = HasSingleCallback<T> extends true ? T[keyof T] : never;

package/out/utility/types.luau

@@ -0,0 +1,22 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Alias for destructors, which is just a callback.
+	 
+]]
+--[[
+	*
+	 * Checks whether `T` is a union.
+	 
+]]
+--[[
+	*
+	 * Checks whether this interface contains a single field, which is also a Callback.
+	 
+]]
+--[[
+	*
+	 * If this interface contains a single callback, extract its type.
+	 
+]]
+return nil

package/out/utility/writable.d.ts

@@ -0,0 +1,4 @@
+export type ToWritable<T> = T extends ReadonlySet<infer V> ? Set<V> : T extends ReadonlyMap<infer K, infer V> ? Map<K, V> : Writable<T>;
+export type WritableState<T> = Writable<{
+    [k in keyof T]: ToWritable<T[k]>;
+}>;

package/out/utility/writable.luau

@@ -0,0 +1,2 @@
+-- Compiled with roblox-ts v3.0.0
+return nil

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@flamework-experimental/core",
+  "version": "2.0.0-alpha.0",
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rbxts-flamework/core.git"
+  },
+  "files": [
+    "out",
+    "flamework.build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.948",
+    "roblox-ts": "^3.0.0"
+  },
+  "dependencies": {
+    "@rbxts/maid": "^1.0.0-ts.1",
+    "@rbxts/object-utils": "^1.0.4",
+    "@rbxts/services": "^1.1.4",
+    "@rbxts/signal": "^1.0.3",
+    "@rbxts/t": "^3.1.0"
+  }
+}