tracyspells / mara Goto Github PK

Begin working on documentation for Mara

Create a workflow that does the following:

• Make a new release with designated version/tag
• Publish Mara to wally and as a rbxm file
• Create a changelog that displays what happened between releases

Currently, Mara.Document has the following methods:

• :undo()
• :redo()
• :redoAll()
• :undoAll()
• :edit()

These methods help keep track of a document's edits. Unfortunately, as Mara.Document's API grows and changes, new ideas for methods would have to deal with "building around" this history. I need to convert createVault into documentHistory, an class that keeps track of a document's edits.

This should be a utility function and not something that's built in. document:edit() will keep its functionality before this "edit tracker" came along. documentHistory should have :undo() and :redo() built in, and use document:changed() to track changes. We're gonna need the :overwrite() method if we're going through with this.

Orignally, this method was inspired by Reflex's CombineProducers method. At this point I don't think this method should be in the API moving forward.

Essentially what stapleDocuments does is this:

type DocumentMap = types.DocumentMap

local function stapleDocuments(documents: DocumentMap)
	local contents = {}

	for name, document in documents do
		contents[name] = document:read()
	end

	return createDocument(contents)
end

I don't like this because users would have to maintain a bigger state, and with nested tables, state becomes a nightmare to manage.
I like Redux's Slices, but I don't want the slices to be combined into one big state. I want the slices to retain their individuality, allowing users to use slice actions and whatnot. So, I propose the ideal "stapleDocuments":

local documents = {}
for _, document in script:GetChildren() do
    if not document:IsA("ModuleScript") then
        continue
    end
    
    documents[document.Name] = require(document)
end

This way, users can lookup the needed document from documents and use its methods.

It would be nice if Mara.createDocument() supported non-table values, e.g.:

local counter = createDocument(0)

...and to make changes to the counter document, we can do:

counter:edit(function(count)
      return count + 1
end)

This would make creating documents a bit more simpler, especially if you're working with primitive values.

A potential problem (for future me) if this feature were to be implemented is how this would integrate with .watch() and .watchFor() utility functions. As of writing this, they only work for tables, but adding this feat shouldn't be too much of an issue.

Mara needs a createSelector function that takes in a section of document contents, and memoizes it, making sure that the selection only changes when necessary.

The reason #11 was made was ultimately because of this issue.

Networking

Mara needs a simple, yet effective solution to send snapshots of state across the server-client boundary.

Basic sketch of what this would look like:

Server
On the server side, Mara will introduce the exporter class.
exporter methods:

• :exportContents() --> exports delta or full snapshot of the shared document contents to the client
• :filterContents() --> is called before :exportContents(), used to filter or modify document contents before being sent to the client

Client
On the client side, Mara will introduce the importer class.
importer has only one method:

• :importContents() --> imports a delta or full snapshot of the shared document contents sent by the server

Shared
In order for both sides to actually function, exporter and importer both need sharedDocuments. The proposed solution in #11 would be great for this, since I can use Mara.watch(...) to detect changes for each document and work with the new states produced on the server.

Questions

1. When sending delta state, should we utilize delta compression? If yes, I think the following libraries can help make the process easier:
   • RemotePacketSizeCounter
   • DeltaCompress