@rbxts/replion 1.0.0

package/README.md

@@ -0,0 +1,5 @@
+# Replion
+
+## Install
+Install with [wally](https://wally.run/):\
+`Replion = "shouxtech/replion@1.0.0"`

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@rbxts/replion",
+  "version": "1.0.0",
+  "description": "",
+  "main": "src/init.lua",
+  "scripts": {},
+  "keywords": [],
+  "author": "CriShoux",
+  "license": "ISC",
+  "type": "commonjs",
+  "types": "src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.896",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@rbxts/sift": "^0.0.11",
+    "@rbxts/sleitnick-signal": "^1.0.8"
+  }
+}

package/src/Client.lua

@@ -0,0 +1,146 @@
+--!strict
+local Shared = require(script.Parent.Shared);
+local Signal = require(dependencies:FindFirstChild('Signal') or dependencies['sleitnick-signal']);
+
+type Observer = (newValue: any, oldValue: any) -> ();
+
+local remote = script.Parent:WaitForChild(Shared.REMOTE_NAME) :: RemoteEvent;
+
+local function deepMergeAndApply(target: any, updates: any)
+	for key, value in updates do
+		if value == Shared.NIL_SENTINEL then
+			target[key] = nil;
+		elseif typeof(value) == 'table' and typeof(target[key]) == 'table' then
+			deepMergeAndApply(target[key], value);
+		else
+			target[key] = value;
+		end;
+	end;
+end;
+
+local Client = {};
+Client.__index = Client;
+
+type Replion = typeof(setmetatable({}, Client));
+
+Client._activeReplions = {} :: { [string]: Replion };
+Client._replionInitializedSignals = {} :: { [string]: Signal.Signal<Replion> };
+
+function Client.waitForReplion(channel: string)
+	local existing = Client._activeReplions[channel];
+	if existing then return existing; end;
+
+	local initSignal = Client._replionInitializedSignals[channel];
+	if initSignal then return initSignal:Wait(); end;
+
+	initSignal = Signal.new();
+	Client._replionInitializedSignals[channel] = initSignal;
+
+	remote:FireServer('I', channel);
+
+	local replion = initSignal:Wait();
+
+	Client._replionInitializedSignals[channel] = nil;
+
+	return replion;
+end;
+
+function Client.new(channel: string, data: Shared.GenericDataTable)
+	local self = setmetatable({}, Client);
+
+	self.channel = channel;
+	self.data = data;
+	self._signals = {} :: { [string]: any };
+	self._allSignal = Signal.new();
+
+	return self;
+end;
+
+function Client:get(key: (string | {string})?)
+	if not key then return self.data; end;
+	if typeof(key) == 'table' then
+		return Shared.getNestedValue(self.data, key);
+	end;
+
+	return self.data[key];
+end;
+
+function Client:observe(key: string?, callback: Observer)
+	if not key then
+		task.spawn(callback, self.data, nil);
+
+		return self._allSignal:Connect(callback);
+	end;
+
+	if not self._signals[key] then
+		self._signals[key] = Signal.new();
+	end;
+
+	task.spawn(callback, self.data[key], nil);
+
+	return self._signals[key]:Connect(callback);
+end;
+
+function Client:_applyUpdates(updates: Shared.GenericDataTable)
+	local oldData = table.clone(self.data); -- Note: Shallow copy instead of deep copy.
+
+	deepMergeAndApply(self.data, updates);
+
+	local anyChanged = false;
+
+	for key, newValue in updates do
+		local oldValue = oldData[key];
+
+		-- If it's a table, we assume it changed if it's in the update list.
+		if typeof(newValue) == 'table' then
+			anyChanged = true
+			local signal = self._signals[key];
+			if signal then
+				signal:Fire(self.data[key], self.data[key]); -- Note: Sends improper 'old' argument due to shallow copy optimization.
+			end;
+		elseif self.data[key] ~= oldValue then
+			anyChanged = true;
+			local signal = self._signals[key];
+			if signal then
+				signal:Fire(self.data[key], oldValue);
+			end;
+		end;
+	end;
+
+	if anyChanged then
+		self._allSignal:Fire(self.data, updates);
+	end;
+end;
+
+function Client:destroy()
+	self._allSignal:Destroy();
+	for _, signal in self._signals do
+		signal:Destroy();
+	end;
+	self._signals = {};
+end;
+
+remote.OnClientEvent:Connect(function(type, channel, payload)
+	if type == 'I' then
+		local newReplion = Client.new(channel, payload);
+		Client._activeReplions[channel] = newReplion;
+		
+		local initializedSignal = Client._replionInitializedSignals[channel];
+		if not initializedSignal then return; end;
+
+		initializedSignal:Fire(newReplion);
+	elseif type == 'U' then
+		local replion = Client._activeReplions[channel];
+		if not replion then return; end;
+
+		replion:_applyUpdates(payload);
+	elseif type == 'D' then
+		local replion = Client._activeReplions[channel]
+		if not replion then return; end;
+
+		replion:destroy();
+		Client._activeReplions[channel] = nil;
+	end;
+end);
+
+return Client;

package/src/Server.lua

@@ -0,0 +1,195 @@
+--!strict
+local Players = game:GetService('Players');
+
+local dependencies = script.Parent.Parent;
+local Shared = require(script.Parent.Shared);
+local Sift = require(dependencies:FindFirstChild('Sift') or dependencies.sift.out);
+
+type ServerConfig = {
+	channel: string;
+	replicateTo: Player?;
+	data: Shared.GenericDataTable;
+};
+
+local remote = script.Parent:FindFirstChild(Shared.REMOTE_NAME) :: RemoteEvent;
+if not remote then
+	remote = Instance.new('RemoteEvent');
+	remote.Name = Shared.REMOTE_NAME;
+	remote.Parent = script.Parent;
+end;
+
+local function setNestedValue(root: any, path: {string}, value: any)
+	local current = root;
+	for i = 1, #path - 1 do
+		local key = path[i];
+		if typeof(current[key]) ~= 'table' then
+			current[key] = {};
+		end;
+		current = current[key];
+	end;
+
+	local lastKey = path[#path];
+	local oldValue = current[lastKey];
+	current[lastKey] = value;
+	return oldValue;
+end;
+
+local function queueNestedUpdate(queue: any, path: {string}, value: any)
+	local current = queue;
+	for i = 1, #path - 1 do
+		local key = path[i];
+		if typeof(current[key]) ~= 'table' then
+			current[key] = {};
+		end;
+		current = current[key];
+	end;
+
+	current[path[#path]] = if value == nil then Shared.NIL_SENTINEL else value;
+end;
+
+local Server = {};
+Server.__index = Server;
+
+type Replion = typeof(setmetatable({}, Server));
+
+Server._activeReplions = {} :: { [Player]: { [string]: Replion } };
+Server._globalReplions = {} :: { [string]: Replion };
+
+-- This method is private because this it isn't able to give correct types for the found Replion, and that's unideal for public use.
+function Server._getPlayerReplion(player: Player, channel: string)
+	local playerReplions = Server._activeReplions[player];
+	if not playerReplions then return nil; end;
+
+	return playerReplions[channel];
+end;
+
+-- This method is private because this it isn't able to give correct types for the found Replion, and that's unideal for public use.
+function Server._getGlobalReplion(channel: string)
+	return Server._globalReplions[channel];
+end;
+
+function Server.new(config: ServerConfig)
+	local self = setmetatable({}, Server);
+
+	self.player = config.replicateTo;
+	self.channel = config.channel;
+	self.data = table.clone(config.data);
+
+	self._queuedUpdates = {} :: Shared.GenericDataTable;
+	self._isQueued = false;
+	self._destroyed = false;
+
+	if self.player then
+		local playerReplions = Server._activeReplions[self.player];
+		if not playerReplions then
+			playerReplions = {};
+			Server._activeReplions[self.player] = playerReplions;
+		end;
+		playerReplions[self.channel] = self;
+	else
+		Server._globalReplions[self.channel] = self;
+	end;
+
+	return self;
+end;
+
+function Server:set(key: string | {string}, value: any)
+	if self._destroyed then return; end;
+
+	local path = if typeof(key) == 'table' then key else {key};
+	local oldValue = Shared.getNestedValue(self.data, path);
+
+	local newValue = if typeof(value) == 'function' then value(oldValue) else value;
+
+	if oldValue == newValue then return; end;
+
+	setNestedValue(self.data, path, newValue);
+	queueNestedUpdate(self._queuedUpdates, path, newValue);
+	self:_scheduleUpdatesFlush();
+end;
+
+function Server:get(key: (string | {string})?)
+	if not key then return self.data; end;
+	if typeof(key) == 'table' then
+		return Shared.getNestedValue(self.data, key);
+	end;
+
+	return self.data[key];
+end;
+
+function Server:destroy()
+	self._destroyed = true;
+	self.data = {};
+	self._queuedUpdates = {};
+
+	if self.player then
+		local playerReplions = self._activeReplions[self.player];
+		if not playerReplions then return; end;
+
+		playerReplions[self.channel] = nil;
+		remote:FireClient(self.player, 'D', self.channel);
+	else
+		self._globalReplions[self.channel] = nil;
+		remote:FireAllClients('D', self.channel);
+	end;
+end;
+
+function Server:_scheduleUpdatesFlush()
+	if self._isQueued then return; end;
+	self._isQueued = true;
+
+	task.defer(function()
+		if self._destroyed then return; end;
+		self:_flushUpdates();
+	end);
+end;
+
+function Server:_flushUpdates()
+	self._isQueued = false;
+
+	local updates = self._queuedUpdates;
+
+	local nUpdates = Sift.Dictionary.count(updates);
+	if nUpdates == 0 then return; end;
+
+	if self.player then
+		remote:FireClient(self.player, 'U', self.channel, updates);
+	else
+		remote:FireAllClients('U', self.channel, updates);
+	end;
+	self._queuedUpdates = {};
+end;
+
+function Server:_sendInitial(player: Player?)
+	local receiver = player or self.player;
+	if not receiver then return; end;
+
+	remote:FireClient(receiver, 'I', self.channel, self.data);
+end;
+
+remote.OnServerEvent:Connect(function(player, action, ...)
+	if action == 'I' then
+		local channel = ...;
+		if not channel then return; end;
+
+		local replion = Server._getPlayerReplion(player, channel);
+		if not replion then
+			replion = Server._getGlobalReplion(channel);
+			if not replion then return; end;
+		end;
+
+		replion:_sendInitial(player);
+	end;
+end);
+
+Players.PlayerRemoving:Connect(function(player)
+	local playerReplions = Server._activeReplions[player];
+	if not playerReplions then return; end;
+
+	for _, replion in playerReplions do
+		replion:destroy();
+	end;
+	Server._activeReplions[player] = nil;
+end);
+
+return Server;

package/src/Shared.lua

@@ -0,0 +1,18 @@
+--!strict
+export type GenericDataTable = { [string]: any };
+
+local Shared = {};
+
+Shared.REMOTE_NAME = 'ReplionNetwork';
+Shared.NIL_SENTINEL = '\0\0__NIL__\0\0';
+
+function Shared.getNestedValue(root: any, path: {string})
+	local current = root;
+	for _, key in path do
+		if typeof(current) ~= 'table' then return nil; end;
+		current = current[key];
+	end;
+	return current;
+end;
+
+return Shared;

package/src/index.d.ts

@@ -0,0 +1,20 @@
+interface State<T> {
+    get(): T;
+    set(newValue: T): void;
+}
+
+declare namespace Observers {
+    function state<T>(initialValue: T): State<T>;
+    function state<T>(): State<T | undefined>;
+
+    function observeAttribute<T extends AttributeValue>(instance: Instance, attribute: string, callback: (value: T | undefined) => (() => void) | void): () => void;
+    function observeState<T>(state: State<T>, callback: (value: T) => void): () => void;
+    function observePlayers(callback: (player: Player) => (() => void) | void): () => void;
+    function observeCharacters(callback: (char: Model, player: Player) => (() => void) | void): () => void;
+    function observeAttribute<T extends AttributeValue>(instance: Instance, attribute: string, callback: (value: T | undefined) => (() => void) | void): () => void;
+    function observeChildren(instance: Instance, callback: (child: Instance) => (() => void) | void): () => void;
+    function observeTag<T extends Instance>(tag: string, callback: (instance: T) => (() => void) | void, ancestors?: Instance[]): () => void;
+    function observeProperty<P extends Instance, K extends InstancePropertyNames<P>>(instance: P, property: K, callback: (value: P[K]) => (() => void) | void): () => void;
+}
+
+export = Observers;

package/src/init.lua

@@ -0,0 +1,12 @@
+--!strict
+local RunService = game:GetService('RunService');
+
+local Replion = {};
+
+if RunService:IsServer() then
+	Replion.Server = require(script.Server);
+else
+	Replion.Client = require(script.Client);
+end;
+
+return Replion;