@quenty/datastore 3.2.1-canary.8533eea.0 → 3.3.1

package/CHANGELOG.md

@@ -3,7 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.2.1-canary.8533eea.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@3.2.0...@quenty/datastore@3.2.1-canary.8533eea.0) (2021-12-18)
+## [3.3.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@3.3.0...@quenty/datastore@3.3.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/datastore
+
+
+
+
+
+# [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@3.2.0...@quenty/datastore@3.3.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/datastore
 

package/README.md

@@ -1,10 +1,10 @@
 # Quenty's DataStore System
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,6 +13,8 @@
 
 This system is a reliable datastore system designed with promises and asyncronious code in mind, and has been tested on several games. Underlying this system are several key design points.
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/DataStore">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/datastore --save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/datastore",
-  "version": "3.2.1-canary.8533eea.0",
+  "version": "3.3.1",
   "description": "Quenty's Datastore implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -26,16 +26,16 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "3.2.0",
-    "@quenty/loader": "3.1.1",
-    "@quenty/maid": "2.0.1",
-    "@quenty/promise": "3.2.1-canary.8533eea.0",
-    "@quenty/signal": "2.0.0",
-    "@quenty/symbol": "2.0.0",
-    "@quenty/table": "2.1.0"
+    "@quenty/baseobject": "^3.2.1",
+    "@quenty/loader": "^3.1.2",
+    "@quenty/maid": "^2.0.2",
+    "@quenty/promise": "^3.3.1",
+    "@quenty/signal": "^2.0.1",
+    "@quenty/symbol": "^2.0.1",
+    "@quenty/table": "^2.1.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8533eeade3bf6835c0295785c1c326b9abee3222"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Server/DataStore.lua

@@ -1,5 +1,28 @@
---- Wraps the datastore object to provide async cached loading and saving
--- @classmod DataStore
+--[=[
+	Wraps the datastore object to provide async cached loading and saving. See [DataStoreStage] for more API.
+
+	Has the following features
+	* Automatic save
+	* Jitter
+	* De-duplication (only updates data it needs)
+
+	```lua
+	local playerMoneyValue = Instance.new("IntValue")
+	playerMoneyValue.Value = 0
+
+	local dataStore = DataStore.new(DataStoreService:GetDataStore("test"), test-store")
+	dataStore:Load("money", 0):Then(function(money)
+		playerMoneyValue.Value = money
+		dataStore:StoreOnValueChange("money", playerMoneyValue)
+	end):Catch(function()
+		-- TODO: Notify player
+	end)
+
+	```
+
+	@server
+	@class DataStore
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -20,12 +43,22 @@ local DataStore = setmetatable({}, DataStoreStage)
 DataStore.ClassName = "DataStore"
 DataStore.__index = DataStore
 
+--[=[
+	Constructs a new DataStore. See [DataStoreStage] for more API.
+	@param robloxDataStore DataStore
+	@param key string
+]=]
 function DataStore.new(robloxDataStore, key)
 	local self = setmetatable(DataStoreStage.new(), DataStore)
 
 	self._key = key or error("No key")
 	self._robloxDataStore = robloxDataStore or error("No robloxDataStore")
 
+--[=[
+	Prop that fires when saving. Promise will resolve once saving is complete.
+	@prop Saving Signal<Promise>
+	@within DataStore
+]=]
 	self.Saving = Signal.new() -- :Fire(promise)
 	self._maid:GiveTask(self.Saving)
 
@@ -56,10 +89,18 @@ function DataStore.new(robloxDataStore, key)
 	return self
 end
 
+--[=[
+	Returns the full path for the datastore
+	@return string
+]=]
 function DataStore:GetFullPath()
 	return ("RobloxDataStore@%s"):format(self._key)
 end
 
+--[=[
+	Returns whether the datastore failed.
+	@return boolean
+]=]
 function DataStore:DidLoadFail()
 	if not self._loadPromise then
 		return false
@@ -80,7 +121,10 @@ function DataStore:PromiseLoadSuccessful()
 	end)
 end
 
--- Saves all stored data
+--[=[
+	Saves all stored data.
+	@return Promise
+]=]
 function DataStore:Save()
 	if self:DidLoadFail() then
 		warn("[DataStore] - Not saving, failed to load")
@@ -98,7 +142,12 @@ function DataStore:Save()
 	return self:_saveData(self:GetNewWriter())
 end
 
--- Loads data. This returns the originally loaded data.
+--[=[
+	Loads data. This returns the originally loaded data.
+	@param keyName string
+	@param defaultValue any?
+	@return any?
+]=]
 function DataStore:Load(keyName, defaultValue)
 	return self:_promiseLoad()
 		:Then(function(data)

package/src/Server/Modules/DataStoreDeleteToken.lua

@@ -1,5 +1,8 @@
---- Token to use for deleting
--- @classmod DataStoreDeleteToken
+--[=[
+	Token to use for deleting.
+	@server
+	@class DataStoreDeleteToken
+]=]
 
 local require = require(script.Parent.loader).load(script)
 

package/src/Server/Modules/DataStoreStage.lua

@@ -1,8 +1,12 @@
---- Provides a data storage facility with an ability to get sub-stores. So you can write
--- directly to this store, overwriting all children, or you can have more partial control
--- at children level. This minimizes accidently overwriting.
--- The big cost here is that we may leave keys that can't be removed.
--- @classmod DataStoreStage
+--[=[
+	Provides a data storage facility with an ability to get sub-stores. So you can write
+	directly to this store, overwriting all children, or you can have more partial control
+	at children level. This minimizes accidently overwriting.
+	The big cost here is that we may leave keys that can't be removed.
+
+	@server
+	@class DataStoreStage
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -17,6 +21,13 @@ local DataStoreStage = setmetatable({}, BaseObject)
 DataStoreStage.ClassName = "DataStoreStage"
 DataStoreStage.__index = DataStoreStage
 
+--[=[
+	Constructs a new DataStoreStage to load from. Prefer to use DataStore because this doesn't
+	have any way to retrieve this.
+	@param loadName string
+	@param loadParent DataStoreStage?
+	@return DataStoreStage
+]=]
 function DataStoreStage.new(loadName, loadParent)
 	local self = setmetatable(BaseObject.new(), DataStoreStage)
 
@@ -30,6 +41,10 @@ function DataStoreStage.new(loadName, loadParent)
 	return self
 end
 
+--[=[
+	Gets an event that will fire off whenever something is stored at this level
+	@return Signal
+]=]
 function DataStoreStage:GetTopLevelDataStoredSignal()
 	if self._topLevelStoreSignal then
 		return self._topLevelStoreSignal
@@ -40,6 +55,10 @@ function DataStoreStage:GetTopLevelDataStoredSignal()
 	return self._topLevelStoreSignal
 end
 
+--[=[
+	Retrieves the full path of this datastore stage for diagnostic purposes.
+	@return string
+]=]
 function DataStoreStage:GetFullPath()
 	if self._loadParent then
 		return self._loadParent:GetFullPath() .. "." .. tostring(self._loadName)
@@ -48,6 +67,12 @@ function DataStoreStage:GetFullPath()
 	end
 end
 
+--[=[
+	Loads the data at the `name`.
+	@param name string
+	@param defaultValue T?
+	@return Promise<T>
+]=]
 function DataStoreStage:Load(name, defaultValue)
 	if not self._loadParent then
 		error("[DataStoreStage.Load] - Failed to load, no loadParent!")
@@ -93,6 +118,10 @@ function DataStoreStage:_afterLoadGetAndApplyStagedData(name, data, defaultValue
 	end
 end
 
+--[=[
+	Explicitely deletes data at the key
+	@param name string
+]=]
 function DataStoreStage:Delete(name)
 	if self._takenKeys[name] then
 		error(("[DataStoreStage] - Already have a writer for %q"):format(name))
@@ -101,6 +130,9 @@ function DataStoreStage:Delete(name)
 	self:_doStore(name, DataStoreDeleteToken)
 end
 
+--[=[
+	Queues up a wipe of all values. Data must load before it can be wiped.
+]=]
 function DataStoreStage:Wipe()
 	return self._loadParent:Load(self._loadName, {})
 		:Then(function(data)
@@ -126,6 +158,11 @@ function DataStoreStage:Store(name, value)
 	self:_doStore(name, value)
 end
 
+--[=[
+	Gets a sub-datastore that will write at the given name point
+	@param name string
+	@return DataStoreStage
+]=]
 function DataStoreStage:GetSubStore(name)
 	assert(type(name) == "string", "Bad name")
 
@@ -146,6 +183,12 @@ function DataStoreStage:GetSubStore(name)
 	return newStore
 end
 
+--[=[
+	Whenever the ValueObject changes, stores the resulting value in that entry.
+	@param name string
+	@param valueObj Instance -- ValueBase object to store on
+	@return MaidTask
+]=]
 function DataStoreStage:StoreOnValueChange(name, valueObj)
 	assert(type(name) == "string", "Bad name")
 	assert(typeof(valueObj) == "Instance", "Bad valueObj")
@@ -162,6 +205,10 @@ function DataStoreStage:StoreOnValueChange(name, valueObj)
 	return conn
 end
 
+--[=[
+	If these is data not yet written then this will return true
+	@return boolean
+]=]
 function DataStoreStage:HasWritableData()
 	if self._dataToSave then
 		return true
@@ -176,7 +223,10 @@ function DataStoreStage:HasWritableData()
 	return false
 end
 
---- Constructs a writer which provides a snapshot of the current data state to write
+--[=[
+	Constructs a writer which provides a snapshot of the current data state to write
+	@return DataStoreWriter
+]=]
 function DataStoreStage:GetNewWriter()
 	local writer = DataStoreWriter.new()
 	if self._dataToSave then

package/src/Server/Modules/DataStoreWriter.lua

@@ -1,5 +1,8 @@
---- Captures a snapshot of data to write and then merges it with the original
--- @classmod DataStoreWriter
+--[=[
+	Captures a snapshot of data to write and then merges it with the original.
+	@server
+	@class DataStoreWriter
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,6 +13,11 @@ local DataStoreWriter = {}
 DataStoreWriter.ClassName = "DataStoreWriter"
 DataStoreWriter.__index = DataStoreWriter
 
+--[=[
+	Constructs a new DataStoreWriter. In general, you will not use this API directly.
+
+	@return DataStoreWriter
+]=]
 function DataStoreWriter.new()
 	local self = setmetatable({}, DataStoreWriter)
 
@@ -19,10 +27,19 @@ function DataStoreWriter.new()
 	return self
 end
 
+--[=[
+	Sets the ray data to write
+	@param data table
+]=]
 function DataStoreWriter:SetRawData(data)
 	self._rawSetData = Table.deepCopy(data)
 end
 
+--[=[
+	Adds a recursive child writer to use at the key `name`
+	@param name string
+	@param writer DataStoreWriter
+]=]
 function DataStoreWriter:AddWriter(name, writer)
 	assert(type(name) == "string", "Bad name")
 	assert(not self._writers[name], "Writer already exists for name")
@@ -31,7 +48,12 @@ function DataStoreWriter:AddWriter(name, writer)
 	self._writers[name] = writer
 end
 
--- Do merge here
+--[=[
+	Merges the new data into the original value
+
+	@param original table?
+	@return table -- The original table
+]=]
 function DataStoreWriter:WriteMerge(original)
 	original = original or {}
 

package/src/Server/PlayerDataStoreManager.lua

@@ -1,5 +1,9 @@
---- DataStore manager for player that automatically saves on player leave and game close
--- @classmod PlayerDataStoreManager
+--[=[
+	DataStore manager for player that automatically saves on player leave and game close.
+
+	@server
+	@class PlayerDataStoreManager
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -16,7 +20,12 @@ local PlayerDataStoreManager = setmetatable({}, BaseObject)
 PlayerDataStoreManager.ClassName = "PlayerDataStoreManager"
 PlayerDataStoreManager.__index = PlayerDataStoreManager
 
--- @param [keyGenerator] Function that takes in a player, and outputs a key
+--[=[
+	Constructs a new PlayerDataStoreManager.
+	@param robloxDataStore DataStore
+	@param keyGenerator (player) -> string -- Function that takes in a player, and outputs a key
+	@return PlayerDataStoreManager
+]=]
 function PlayerDataStoreManager.new(robloxDataStore, keyGenerator)
 	local self = setmetatable(BaseObject.new(), PlayerDataStoreManager)
 
@@ -49,24 +58,37 @@ function PlayerDataStoreManager.new(robloxDataStore, keyGenerator)
 	return self
 end
 
---- For if you want to disable saving in studio for faster close time!
+--[=[
+	For if you want to disable saving in studio for faster close time!
+]=]
 function PlayerDataStoreManager:DisableSaveOnCloseStudio()
 	assert(RunService:IsStudio())
 
 	self._disableSavingInStudio = true
 end
 
---- Adds a callback to be called before save on removal
+--[=[
+	Adds a callback to be called before save on removal
+	@param callback function
+]=]
 function PlayerDataStoreManager:AddRemovingCallback(callback)
 	table.insert(self._removingCallbacks, callback)
 end
 
---- Callable to allow manual GC so things can properly clean up.
--- This can be used to pre-emptively cleanup players.
+--[=[
+	Callable to allow manual GC so things can properly clean up.
+	This can be used to pre-emptively cleanup players.
+
+	@param player Player
+]=]
 function PlayerDataStoreManager:RemovePlayerDataStore(player)
 	self:_removePlayerDataStore(player)
 end
 
+--[=[
+	@param player Player
+	@return DataStore
+]=]
 function PlayerDataStoreManager:GetDataStore(player)
 	assert(typeof(player) == "Instance", "Bad player")
 	assert(player:IsA("Player"), "Bad player")
@@ -83,6 +105,11 @@ function PlayerDataStoreManager:GetDataStore(player)
 	return self:_createDataStore(player)
 end
 
+--[=[
+	Removes all player data stores, and returns a promise that
+	resolves when all pending saves are saved.
+	@return Promise
+]=]
 function PlayerDataStoreManager:PromiseAllSaves()
 	for player, _ in pairs(self._datastores) do
 		self:_removePlayerDataStore(player)

package/src/Server/Utility/DataStorePromises.lua

@@ -1,5 +1,8 @@
---- Utility methods to interactive with DataStores
--- @module DataStorePromises
+--[=[
+	Utility methods to interactive with Roblox datastores.
+	@server
+	@class DataStorePromises
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -8,6 +11,13 @@ local DataStoreService = game:GetService("DataStoreService")
 
 local DataStorePromises = {}
 
+--[=[
+	Promises a Roblox datastore object with the name and scope. Generally only fails
+	when you haven't published the place.
+	@param name string
+	@param scope string
+	@return Promise<DataStore>
+]=]
 function DataStorePromises.promiseDataStore(name, scope)
 	assert(type(name) == "string", "Bad name")
 	assert(type(scope) == "string", "Bad scope")
@@ -25,6 +35,12 @@ function DataStorePromises.promiseDataStore(name, scope)
 
 end
 
+--[=[
+	Wraps :GetAsync() in a promise
+	@param robloxDataStore DataStore
+	@param key string
+	@return Promise<T>
+]=]
 function DataStorePromises.getAsync(robloxDataStore, key)
 	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
@@ -41,6 +57,14 @@ function DataStorePromises.getAsync(robloxDataStore, key)
 	end)
 end
 
+--[=[
+	Wraps :UpdateAsync() in a promise
+	@param robloxDataStore DataStore
+	@param key string
+	@param updateFunc (T) -> T?
+	@return Promise<boolean>
+]=]
+
 function DataStorePromises.updateAsync(robloxDataStore, key, updateFunc)
 	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
@@ -61,6 +85,13 @@ function DataStorePromises.updateAsync(robloxDataStore, key, updateFunc)
 	end)
 end
 
+--[=[
+	Wraps :SetAsync() in a promise
+	@param robloxDataStore DataStore
+	@param key string
+	@param value string
+	@return Promise<boolean>
+]=]
 function DataStorePromises.setAsync(robloxDataStore, key, value)
 	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
@@ -76,6 +107,13 @@ function DataStorePromises.setAsync(robloxDataStore, key, value)
 	end)
 end
 
+--[=[
+	Wraps :IncrementAsync() in a promise
+	@param robloxDataStore DataStore
+	@param key string
+	@param delta number
+	@return Promise<boolean>
+]=]
 function DataStorePromises.promiseIncrementAsync(robloxDataStore, key, delta)
 	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
@@ -92,6 +130,12 @@ function DataStorePromises.promiseIncrementAsync(robloxDataStore, key, delta)
 	end)
 end
 
+--[=[
+	Wraps :RemoveAsync() in a promise
+	@param robloxDataStore DataStore
+	@param key string
+	@return Promise<boolean>
+]=]
 function DataStorePromises.removeAsync(robloxDataStore, key)
 	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")