@trioforge/crucible 0.0.0-stage → 0.2.0

package/out/data.luau

@@ -0,0 +1,97 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _declarations = TS.import(script, script.Parent, "internal", "data", "declarations")
+local markServerOnly = _declarations.markServerOnly
+local replicatedPathsOf = _declarations.replicatedPathsOf
+--* A value a save can hold: JSON, with absent keys for values that admit `undefined`. 
+--* A saved record: string keys to JSON. 
+--[[
+	*
+	 * One schema step. It gets a private copy of the stored record, unknown keys included, as plain JSON, and returns a
+	 * patch: an object merges into the stored object, any other value replaces the stored one, and an omitted key is kept.
+	 * A step cannot delete a key. Steps are append-only and must be pure.
+	 
+]]
+--[[
+	*
+	 * The identity of one logical operation, kept across its retries. Only `operationId()` makes one; a plain string does
+	 * not type-check. It carries its creation time, which bounds how long it deduplicates.
+	 
+]]
+--* Why a store call did not complete. 
+--* A store call's result: narrow `ok` before reading `value`. 
+--[[
+	*
+	 * A template field the owner's client never receives. The brand is phantom; `serverOnly(value)` also marks the value at
+	 * runtime, and the declaration checks that the two agree.
+	 
+]]
+--* What the server reads and writes: the template's type with every `ServerOnly` unwrapped, deeply readonly. 
+--* A `ServerOnly` field, or a plain object field whose every field is server-only in turn. 
+--[[
+	*
+	 * What the owner's client reads: every `ServerOnly` field removed, and every plain object left with no field, at any
+	 * depth. Deeply readonly.
+	 
+]]
+--* A store's server data type, for helper signatures: `export type PlayerData = Profile<typeof PlayerData>`. 
+--* A store's client data type. 
+--[[
+	*
+	 * A server handle's own members. `h()` reads, tracked and frozen; while the profile is not writable it returns the
+	 * template's value at the path. `set` and `update` are one write each through the store's gate and return its result.
+	 
+]]
+--* An array handle's writes. Indices are TypeScript's, from 0. 
+--* A server handle at a position of type `V`: reads `V | A`, writes `V`, and reaches its children by key. 
+--* A client handle: the same paths and reads as the server's, and no writes. 
+--* Why a profile loaded. 
+--* Why a profile is releasing. 
+--* A developer product purchase, read from Roblox's receipt. 
+--[[
+	*
+	 * A grant callback's fourth argument. It stages an effect that runs once, on a fresh thread, after the grant is durably
+	 * saved and before the purchase is acknowledged; never after a refused grant.
+	 
+]]
+--* A field holding it is the claim. Not callable. 
+--* A durable message to one player's profile, declared in a server module. Invariant in `P`. 
+--* One quarantined message, for recovery tooling. The payload is the stored JSON, unknown keys included. 
+--* Why a save or handoff did not confirm. 
+--* A save or handoff result: narrow `ok` first. 
+--[[
+	*
+	 * A profile store: one shared declaration, callable on both sides. The server calls it with a player for that player's
+	 * writable handle; the client calls it with nothing for the local player's read-only handle.
+	 
+]]
+--* A profile store's options. 
+--* The handle member names. A template key with one of these names, at any depth, does not compile. 
+--[[
+	*
+	 * Declares a profile store by its DataStore name. It must initialize an exported top-level const in a shared module.
+	 * The type comes from `template`; annotate empty collections and optional fields with `as`.
+	 
+]]
+local function profileStore(_name, _options)
+	error("Crucible data needs the @trioforge/crucible/transformer plugin")
+end
+--* Marks a template field server-only: the owner's client never receives it. 
+local function serverOnly(value)
+	return markServerOnly(value)
+end
+--[[
+	*
+	 * The exact field paths the owner's client receives, each an array of segments: an object field's key, "[]" for an
+	 * array element and "*" for a map value. A key that is "[]" or "*", or starts with a backslash, gets one more backslash.
+	 * Sorted segment by segment, by bytes.
+	 
+]]
+local function replicatedPaths(store)
+	return replicatedPathsOf(store)
+end
+return {
+	profileStore = profileStore,
+	serverOnly = serverOnly,
+	replicatedPaths = replicatedPaths,
+}

package/out/emit/configs.d.ts

@@ -0,0 +1,4 @@
+import type { Config, PlayerConfig } from "../configs";
+import type { Node } from "../internal/network/schema";
+export declare function config<T>(name: string, fallback: T, value: Node): Config<T>;
+export declare function playerConfig<T>(name: string, fallback: T, value: Node): PlayerConfig<T>;

package/out/emit/configs.luau

@@ -0,0 +1,22 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _runtime = TS.import(script, script.Parent.Parent, "internal", "configs", "runtime")
+local declare = _runtime.declare
+local readGlobal = _runtime.readGlobal
+local readPlayer = _runtime.readPlayer
+local function config(name, fallback, value)
+	local declaration = declare(name, "global", fallback, value)
+	return function()
+		return readGlobal(declaration)
+	end
+end
+local function playerConfig(name, fallback, value)
+	local declaration = declare(name, "player", fallback, value)
+	return function(player)
+		return readPlayer(declaration, player)
+	end
+end
+return {
+	config = config,
+	playerConfig = playerConfig,
+}

package/out/emit/data.d.ts

@@ -0,0 +1,6 @@
+import type { ProfileMessage, ProfileOptions, ProfileStore } from "../data";
+import type { Node } from "../internal/network/schema";
+import type { DataStore, StoreOptions } from "../server/data";
+export declare function dataStore<T extends object>(name: string, options: StoreOptions<NoInfer<T>>, value: Node): DataStore<T>;
+export declare function profileStore<T extends object>(name: string, options: ProfileOptions<T>, persist: Node, replica: Node, serverOnlyPaths: readonly (readonly string[])[]): ProfileStore<T>;
+export declare function profileMessage<P>(name: string, payload: Node): ProfileMessage<P>;

package/out/emit/data.luau

@@ -0,0 +1,19 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local declareProfileStore = TS.import(script, script.Parent.Parent, "internal", "data", "declarations").declareProfileStore
+local declareProfileMessage = TS.import(script, script.Parent.Parent, "internal", "data", "messages").declareProfileMessage
+local declareRecords = TS.import(script, script.Parent.Parent, "internal", "data", "record-declarations").declareRecords
+local function dataStore(name, options, value)
+	return declareRecords(name, options.defaults, options.migrations, value)
+end
+local function profileStore(name, options, persist, replica, serverOnlyPaths)
+	return declareProfileStore(name, options.template, options.migrations, persist, replica, serverOnlyPaths)
+end
+local function profileMessage(name, payload)
+	return declareProfileMessage(name, payload)
+end
+return {
+	dataStore = dataStore,
+	profileStore = profileStore,
+	profileMessage = profileMessage,
+}

package/out/emit/index.d.ts

@@ -0,0 +1,45 @@
+export { n } from "../internal/network/schema";
+export { config, playerConfig } from "./configs";
+export { toServer, toClient, askServer, receive } from "./network";
+export { replicated, replicatedPerPlayer } from "./replicated";
+export { dataStore, profileStore, profileMessage } from "./data";
+import type { All } from "../all";
+import type { CrucibleObject } from "../crucible-object";
+export type EmittedDep = string | {
+    readonly all: string;
+};
+interface EmittedBase {
+    readonly id: string;
+    readonly deps: readonly EmittedDep[];
+    readonly provides: readonly string[];
+}
+export type EmittedClass = (EmittedBase & {
+    readonly kind: "subsystem";
+}) | (EmittedBase & {
+    readonly kind: "behaviour";
+    readonly tag: string;
+    readonly instance: readonly (keyof Instances)[];
+    readonly attributes?: {
+        readonly [field: string]: EmittedAttribute;
+    };
+});
+export type Check = (value: unknown) => boolean;
+export declare function defineClass(klass: new (...args: never[]) => CrucibleObject, emitted: EmittedClass): void;
+export declare function resolve<T extends object>(id: string): T;
+export declare function resolveAll<T extends object>(id: string): All<T>;
+export declare const t: {
+    readonly string: Check;
+    readonly number: Check;
+    readonly boolean: Check;
+    readonly vector3: Check;
+    readonly color3: Check;
+    readonly literal: (expected: string | number | boolean) => Check;
+    readonly optional: (check: Check) => Check;
+    readonly union: (...checks: Check[]) => Check;
+};
+export interface EmittedAttribute {
+    readonly name: string;
+    readonly check: Check;
+    readonly required: boolean;
+}
+export declare function attribute<T>(object: object, field: string, fallback?: T): T;

package/out/emit/init.luau

@@ -0,0 +1,101 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local readClaim = TS.import(script, script.Parent, "internal", "construction-claim").readClaim
+exports.n = TS.import(script, script.Parent, "internal", "network", "schema").n
+local _configs = TS.import(script, script, "configs")
+exports.config = _configs.config
+exports.playerConfig = _configs.playerConfig
+local _network = TS.import(script, script, "network")
+exports.toServer = _network.toServer
+exports.toClient = _network.toClient
+exports.askServer = _network.askServer
+exports.receive = _network.receive
+local _replicated = TS.import(script, script, "replicated")
+exports.replicated = _replicated.replicated
+exports.replicatedPerPlayer = _replicated.replicatedPerPlayer
+local _data = TS.import(script, script, "data")
+exports.dataStore = _data.dataStore
+exports.profileStore = _data.profileStore
+exports.profileMessage = _data.profileMessage
+local _registry = TS.import(script, script.Parent, "internal", "registry")
+local define = _registry.define
+local resolveOne = _registry.resolveOne
+local setFor = _registry.setFor
+local function defineClass(klass, emitted)
+	define(klass, emitted)
+end
+local function resolve(id)
+	return resolveOne(id)
+end
+local function resolveAll(id)
+	return setFor(id)
+end
+local t = {
+	string = (function(value)
+		local _value = value
+		return type(_value) == "string"
+	end),
+	number = (function(value)
+		local _value = value
+		return type(_value) == "number"
+	end),
+	boolean = (function(value)
+		local _value = value
+		return type(_value) == "boolean"
+	end),
+	vector3 = (function(value)
+		local _value = value
+		return typeof(_value) == "Vector3"
+	end),
+	color3 = (function(value)
+		local _value = value
+		return typeof(_value) == "Color3"
+	end),
+	literal = function(expected)
+		return function(value)
+			return value == expected
+		end
+	end,
+	optional = function(check)
+		return function(value)
+			return value == nil or check(value)
+		end
+	end,
+	union = function(...)
+		local checks = { ... }
+		return function(value)
+			-- ▼ ReadonlyArray.some ▼
+			local _result = false
+			local _callback = function(check)
+				return check(value)
+			end
+			for _k, _v in checks do
+				if _callback(_v, _k - 1, checks) then
+					_result = true
+					break
+				end
+			end
+			-- ▲ ReadonlyArray.some ▲
+			return _result
+		end
+	end,
+}
+local function attribute(object, field, fallback)
+	local claim = readClaim()
+	if claim == nil or claim.object ~= object then
+		error("attribute read outside construction claim")
+	end
+	local _value = claim.attributes
+	if _value ~= nil then
+		_value = _value[field]
+	end
+	local value = _value
+	return if value == nil then fallback else value
+end
+exports.defineClass = defineClass
+exports.resolve = resolve
+exports.resolveAll = resolveAll
+exports.attribute = attribute
+exports.t = t
+return exports

package/out/emit/network.d.ts

@@ -0,0 +1,6 @@
+import type { AskServer, ReceiveCallback, Receiver, ReceiveTarget, ToClient, ToServer } from "../network";
+import type { Node } from "../internal/network/schema";
+export declare function toServer<P>(name: string, payload: Node): ToServer<P>;
+export declare function toClient<P>(name: string, payload: Node): ToClient<P>;
+export declare function askServer<Request, Response>(name: string, request: Node, response: Node, timeout: number | undefined): AskServer<Request, Response>;
+export declare function receive<T extends ReceiveTarget>(owner: object, field: string, target: T, callback: ReceiveCallback<T>): Receiver;

package/out/emit/network.luau

@@ -0,0 +1,36 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local define = TS.import(script, script.Parent.Parent, "internal", "network", "catalog").define
+local claim = TS.import(script, script.Parent.Parent, "internal", "network", "claims").claim
+local function toServer(name, payload)
+	return define({
+		kind = "to-server",
+		name = name,
+		input = payload,
+	})
+end
+local function toClient(name, payload)
+	return define({
+		kind = "to-client",
+		name = name,
+		input = payload,
+	})
+end
+local function askServer(name, request, response, timeout)
+	return define({
+		kind = "ask-server",
+		name = name,
+		input = request,
+		output = response,
+		timeout = timeout,
+	})
+end
+local function receive(owner, field, target, callback)
+	return claim(owner, field, target, callback)
+end
+return {
+	toServer = toServer,
+	toClient = toClient,
+	askServer = askServer,
+	receive = receive,
+}

package/out/emit/replicated.d.ts

@@ -0,0 +1,4 @@
+import type { Node } from "../internal/network/schema";
+import type { Replicated, ReplicatedPerPlayer } from "../replicated";
+export declare function replicated<T>(name: string, initial: NoInfer<T>, value: Node): Replicated<T>;
+export declare function replicatedPerPlayer<T>(name: string, initial: NoInfer<T>, value: Node): ReplicatedPerPlayer<T>;

package/out/emit/replicated.luau

@@ -0,0 +1,13 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local declareReplicated = TS.import(script, script.Parent.Parent, "internal", "sync", "declarations").declareReplicated
+local function replicated(name, initial, value)
+	return declareReplicated("all", name, initial, value)
+end
+local function replicatedPerPlayer(name, initial, value)
+	return declareReplicated("player", name, initial, value)
+end
+return {
+	replicated = replicated,
+	replicatedPerPlayer = replicatedPerPlayer,
+}

package/out/index.d.ts

@@ -0,0 +1,20 @@
+export { Subsystem } from "./subsystem";
+export type { CrucibleObject } from "./crucible-object";
+export type { All } from "./all";
+export { inject } from "./inject";
+export { attribute } from "./attribute";
+export { CrucibleBehaviour, type BehaviourClass } from "./crucible-behaviour";
+export interface BootOptions {
+    readonly load: readonly string[];
+    readonly fixedRate?: number;
+}
+export { Logging, LogLevel } from "./logging";
+export type { Logger, LogRecord, LogSink, SinkSubscription, LogContext, LogProperties } from "./logging";
+export { state, computed, effect, watch, untracked, scope, onCleanup, own } from "./reactive";
+export type { Readable, State, Ownable } from "./reactive";
+export { replicated, replicatedPerPlayer, syncStatus } from "./replicated";
+export type { Replicated, ReplicatedPerPlayer, SyncStatus } from "./replicated";
+export { toServer, toClient, askServer, receive, ClientReady } from "./network";
+export type { ToServer, ToClient, AskServer, Receiver, ReceiveTarget, ReceiveCallback, AskResult, AskFailure, AskOptions, PayloadArgs, f32, f64, u8, u16, u32, } from "./network";
+export { profileStore, serverOnly, replicatedPaths } from "./data";
+export type { ProfileStore, ProfileOptions, ServerOnly, ProfileData, ClientData, Profile, ClientProfile, DataHandle, ReadHandle, WriteHandle, ArrayWrites, ReservedName, Json, JsonRecord, Migration, } from "./data";

package/out/init.luau

@@ -0,0 +1,34 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+exports.Subsystem = TS.import(script, script, "subsystem").Subsystem
+exports.inject = TS.import(script, script, "inject").inject
+exports.attribute = TS.import(script, script, "attribute").attribute
+exports.CrucibleBehaviour = TS.import(script, script, "crucible-behaviour").CrucibleBehaviour
+local _logging = TS.import(script, script, "logging")
+exports.Logging = _logging.Logging
+exports.LogLevel = _logging.LogLevel
+local _reactive = TS.import(script, script, "reactive")
+exports.state = _reactive.state
+exports.computed = _reactive.computed
+exports.effect = _reactive.effect
+exports.watch = _reactive.watch
+exports.untracked = _reactive.untracked
+exports.scope = _reactive.scope
+exports.onCleanup = _reactive.onCleanup
+exports.own = _reactive.own
+local _replicated = TS.import(script, script, "replicated")
+exports.replicated = _replicated.replicated
+exports.replicatedPerPlayer = _replicated.replicatedPerPlayer
+exports.syncStatus = _replicated.syncStatus
+local _network = TS.import(script, script, "network")
+exports.toServer = _network.toServer
+exports.toClient = _network.toClient
+exports.askServer = _network.askServer
+exports.receive = _network.receive
+exports.ClientReady = _network.ClientReady
+local _data = TS.import(script, script, "data")
+exports.profileStore = _data.profileStore
+exports.serverOnly = _data.serverOnly
+exports.replicatedPaths = _data.replicatedPaths
+return exports

package/out/inject.d.ts

@@ -0,0 +1 @@
+export declare function inject<T extends object>(): T;

package/out/inject.luau

@@ -0,0 +1,7 @@
+-- Compiled with roblox-ts v3.0.0
+local function inject()
+	error("inject<T>() was not replaced; add the Crucible transformer to the compiler plugins")
+end
+return {
+	inject = inject,
+}

package/out/internal/binding.d.ts

@@ -0,0 +1 @@
+export {};