cluaupp 1.5.0 → 1.5.1

package/examples/game/libs/Keep/Engine.luau

@@ -0,0 +1,211 @@
+--!strict
+-- Kernel bridge for CL++ Server/Client. Path tokens, Keep Store, Data,
+-- tagged-buffer replication, and Spark stay Luau — CL++ 0.3.2 cannot express
+-- type functions, metatable path tokens, or rawset overlays.
+
+local RunService = game:GetService("RunService")
+
+local Path = require(script.Parent.Path)
+local Data = require(script.Parent.Data)
+local Enums = require(script.Parent.Enums)
+local EnumModule = require(script.Parent.Enum)
+local Store = require(script.Parent.Store)
+local Trade = require(script.Parent.Trade)
+local ReplicatorModule = require(script.Parent.Replicator)
+local Spark = require(script.Parent.Parent.Spark)
+
+local Engine = {}
+
+Engine.Path = Path
+Engine.Data = Data
+Engine.ProfileStore = Store
+Engine.Store = Store
+Engine.Trade = Trade
+Engine.Enums = Enums
+Engine.Enum = EnumModule
+Engine.Signal = Spark
+Engine.Spark = Spark
+Engine.Replicator = if RunService:IsServer() then ReplicatorModule.Server else ReplicatorModule.Client
+
+function Engine:mapNew()
+	return {}
+end
+
+function Engine:mapSet(map: any, key: any, value: any)
+	if map then
+		map[key] = value
+	end
+end
+
+function Engine:mapGet(map: any, key: any): any
+	if map == nil then
+		return nil
+	end
+	return map[key]
+end
+
+function Engine:mapClear(map: any, key: any)
+	if map then
+		map[key] = nil
+	end
+end
+
+function Engine:createTemplatePaths(tmpl: any)
+	return Path.createTemplatePaths(tmpl)
+end
+
+function Engine:rootToken()
+	return Path.rootToken()
+end
+
+function Engine:toKey(path: any): string
+	return Path.toKey(path)
+end
+
+function Engine:parentPath(path: any)
+	return Path.parent(path)
+end
+
+function Engine:emptyPath()
+	return {}
+end
+
+function Engine:dataNew(initial: any, writable: boolean, strictPaths: boolean?, autoCreate: boolean?, tmpl: any)
+	return Data.new(initial, writable, {
+		StrictPaths = if strictPaths ~= nil then strictPaths else true,
+		AutoCreateMissingTables = if autoCreate ~= nil then autoCreate else false,
+		Template = if tmpl ~= nil then tmpl else initial,
+	})
+end
+
+function Engine:applySet(data: any, path: any, value: any)
+	Data._applySet(data, path, value)
+end
+
+function Engine:applyArrayInsert(data: any, path: any, value: any, index: number?)
+	Data._applyArrayInsert(data, path, value, index)
+end
+
+function Engine:applyArrayRemove(data: any, path: any, index: number)
+	Data._applyArrayRemove(data, path, index)
+end
+
+function Engine:applyTransientSet(data: any, path: any, value: any)
+	Data._applyTransientSet(data, path, value)
+end
+
+function Engine:applyTransientArrayInsert(data: any, path: any, value: any, index: number?)
+	Data._applyTransientArrayInsert(data, path, value, index)
+end
+
+function Engine:applyTransientArrayRemove(data: any, path: any, index: number)
+	Data._applyTransientArrayRemove(data, path, index)
+end
+
+function Engine:applyTransientClear(data: any, path: any)
+	Data._applyTransientClear(data, path)
+end
+
+function Engine:profileStoreNew(storeName: string, tmpl: any)
+	return Store.New(storeName, tmpl)
+end
+
+function Engine:startSession(store: any, key: string, player: Player, players: Players)
+	local profile = store:StartSessionAsync(key, {
+		Cancel = function()
+			return player.Parent ~= players
+		end,
+	})
+	if profile then
+		profile:AddUserId(player.UserId)
+		Trade.Ensure(profile.Data)
+		profile:MessageHandler(function(message, processed)
+			Trade.HandleMessage(profile, message, processed)
+		end)
+	end
+	return profile
+end
+
+function Engine:abortActiveTrade(profile: any)
+	Trade.AbortIfActive(profile)
+end
+
+function Engine:signalNew()
+	return Spark.new()
+end
+
+function Engine:isExcluded(excluded: { [string]: boolean }?, path: any): boolean
+	if not path or #path == 0 then
+		return false
+	end
+	if not excluded then
+		return false
+	end
+	for i = 1, #path do
+		local prefix = table.create(i)
+		for j = 1, i do
+			prefix[j] = path[j]
+		end
+		if excluded[Path.toKey(prefix)] then
+			return true
+		end
+	end
+	return false
+end
+
+function Engine:buildSnapshot(excluded: { [string]: boolean }?, value: any, prefix: any): any
+	local path = prefix or {}
+	if Engine:isExcluded(excluded, path) then
+		return nil
+	end
+	if type(value) ~= "table" then
+		return value
+	end
+	local out = {}
+	for k, v in value do
+		local newPath = table.clone(path)
+		newPath[#newPath + 1] = k
+		if not Engine:isExcluded(excluded, newPath) then
+			out[k] = Engine:buildSnapshot(excluded, v, newPath)
+		end
+	end
+	return out
+end
+
+function Engine:watchData(data: any, player: Player, ready: { [Player]: boolean }, excluded: { [string]: boolean })
+	return data.Changed:Connect(function(action, path, ...)
+		if not ready[player] then
+			return
+		end
+		if Engine:isExcluded(excluded, path) then
+			return
+		end
+		Engine.Replicator:Send(player, action, path, ...)
+	end)
+end
+
+function Engine:replicatorOn(action: string, handler: any)
+	Engine.Replicator:On(action, handler)
+end
+
+function Engine:replicatorNotifyReady()
+	Engine.Replicator:NotifyReady()
+end
+
+function Engine:replicatorSend(player: Player, action: string, path: any, ...)
+	Engine.Replicator:Send(player, action, path, ...)
+end
+
+function Engine:replicatorGetBufferStats(player: Player?)
+	return Engine.Replicator:GetBufferStats(player)
+end
+
+function Engine:replicatorForgetPlayer(player: Player)
+	Engine.Replicator:ForgetPlayer(player)
+end
+
+function Engine:replicatorDestroy()
+	Engine.Replicator:Destroy()
+end
+
+return Engine

package/examples/game/libs/Keep/Enum.luau

@@ -0,0 +1,6 @@
+return table.freeze({
+	OrderList = table.freeze({
+		Asc = "asc",
+		Desc = "desc",
+	}),
+})

package/examples/game/libs/Keep/Enums.luau

@@ -0,0 +1,10 @@
+return table.freeze({
+	Init = "i",
+	Set = "s",
+	ArrayInsert = "ai",
+	ArrayRemove = "ar",
+	SetTransient = "ts",
+	ArrayInsertTransient = "tai",
+	ArrayRemoveTransient = "tar",
+	ClearTransient = "tc",
+})

package/examples/game/libs/Keep/Path.luau

@@ -0,0 +1,236 @@
+const Path = {}
+
+export type Path = { string | number }
+
+type function PathOf(templateType: type): type
+	local function unwrapOptional(valueType: type): type
+		if not valueType:is("union") then
+			return valueType
+		end
+
+		local resolved = nil
+		for _, component in valueType:components() do
+			if not (component:is("singleton") and component:value() == nil) then
+				resolved = if resolved then types.unionof(resolved, component) else component
+			end
+		end
+
+		return resolved or valueType
+	end
+
+	local function mapValue(valueType: type): type
+		valueType = unwrapOptional(valueType)
+
+		if valueType:is("any") or valueType:is("unknown") then
+			return types.newtable()
+		end
+
+		if valueType:is("union") then
+			for _, component in valueType:components() do
+				if component:is("table") then
+					return mapValue(component)
+				end
+			end
+			return types.newtable()
+		end
+
+		if valueType:is("intersection") then
+			local mapped = types.newtable()
+			local hasMembers = false
+
+			for _, component in valueType:components() do
+				if component:is("table") then
+					local sub = mapValue(component)
+					for key in sub:properties() do
+						local childType = sub:readproperty(key)
+						if childType then
+							mapped:setproperty(key, childType)
+							hasMembers = true
+						end
+					end
+
+					local indexerInfo = sub:indexer()
+					if indexerInfo then
+						mapped:setindexer(indexerInfo.index, indexerInfo.readresult)
+						hasMembers = true
+					end
+				end
+			end
+
+			if hasMembers then
+				return mapped
+			end
+		end
+
+		if not valueType:is("table") then
+			local token = types.newtable()
+			token:setproperty("__pathValue", valueType)
+			return token
+		end
+
+		local mapped = types.newtable()
+		local hasMembers = false
+
+		for key in valueType:properties() do
+			local childType = valueType:readproperty(key)
+			if childType then
+				mapped:setproperty(key, mapValue(unwrapOptional(childType)))
+				hasMembers = true
+			end
+		end
+
+		local indexerInfo = valueType:indexer()
+		if indexerInfo then
+			mapped:setindexer(indexerInfo.index, mapValue(indexerInfo.readresult))
+			hasMembers = true
+		end
+
+		if hasMembers then
+			return mapped
+		end
+
+		return types.newtable()
+	end
+
+	return mapValue(templateType)
+end
+
+-- PathTree<T> mirrors the template shape for navigation (Paths).
+export type PathTree<T> = PathOf<T>
+-- PathToken<V> is the typed handle for a leaf path targeting value type V.
+export type PathToken<V> = { __pathValue: V }
+export type TemplatePaths<T> = PathTree<T>
+
+local ROOT_TOKEN: PathTree<{}>? = nil
+
+const clone = function(path: Path?): Path
+	if not path then
+		return {}
+	end
+	local out = table.create(#path)
+	for i, v in path do
+		out[i] = v
+	end
+	return out
+end
+
+local function createToken(segments: Path): any
+	local token = {}
+	rawset(token, "__kdsv2_path_token", true)
+	rawset(token, "__segments", table.freeze(clone(segments)))
+	rawset(token, "__children", nil)
+
+	return setmetatable(token, {
+		__index = function(self, key)
+			if type(key) ~= "string" and type(key) ~= "number" then
+				return nil
+			end
+
+			local children = rawget(self, "__children")
+			if not children then
+				children = {}
+				rawset(self, "__children", children)
+			end
+
+			local cached = children[key]
+			if cached then
+				return cached
+			end
+
+			local nextSegments = clone(rawget(self, "__segments"))
+			nextSegments[#nextSegments + 1] = key
+			local child = createToken(nextSegments)
+			children[key] = child
+			return child
+		end,
+	})
+end
+
+function Path.rootToken(): PathTree<{}>
+	if not ROOT_TOKEN then
+		ROOT_TOKEN = createToken({})
+	end
+	return ROOT_TOKEN :: PathTree<{}>
+end
+
+function Path.createTemplatePaths<T>(template: T, currentSegments: Path?): PathTree<T>
+	local token = createToken(clone(currentSegments))
+
+	if type(template) ~= "table" then
+		rawset(token, "__pathValue", template)
+		return token :: PathTree<T>
+	end
+
+	local children = {}
+	rawset(token, "__children", children)
+
+	for key, value in template do
+		local keyType = type(key)
+		if keyType == "string" or keyType == "number" then
+			local nextSegments = clone(currentSegments)
+			nextSegments[#nextSegments + 1] = key
+
+			local child = Path.createTemplatePaths(value, nextSegments)
+			children[key] = child
+			rawset(token, key, child)
+		end
+	end
+
+	return token :: PathTree<T>
+end
+
+function Path.isToken(value: any): boolean
+	return type(value) == "table" and rawget(value, "__kdsv2_path_token") == true
+end
+
+function Path.toArray(path: Path | PathTree<{}>?): Path?
+	if path == nil then
+		return nil
+	end
+	if Path.isToken(path) then
+		return clone(rawget(path :: any, "__segments"))
+	end
+	return clone(path :: Path)
+end
+
+function Path.validate(path: Path?): boolean
+	if not path then
+		return true
+	end
+	for _, segment in path do
+		local kind = type(segment)
+		if kind ~= "string" and kind ~= "number" then
+			return false
+		end
+	end
+	return true
+end
+
+function Path.toKey(path: Path?): string
+	if not path or #path == 0 then
+		return ""
+	end
+	local parts = table.create(#path)
+	for i, v in path do
+		if type(v) == "string" then
+			parts[i] = "s\1" .. v
+		else
+			parts[i] = "n\1" .. tostring(v)
+		end
+	end
+	return table.concat(parts, "\0")
+end
+
+function Path.clone(path: Path?): Path
+	return clone(path)
+end
+
+function Path.parent(path: Path): Path
+	local out = table.create(math.max(#path - 1, 0))
+	for i = 1, #path - 1 do
+		out[i] = path[i]
+	end
+	return out
+end
+
+return Path