Git Product home page Git Product logo

mara's Introduction

mara

WARNING: This project has been discontinued. Do not use for new work.


Mara is a lightweight state container that allows you to write simple code to manage state in Roblox. It is inspired by Reflex and Valtio.

๐Ÿ“ฆ Installation

You can install Mara on Wally.

Alternatively, you can check out the latest GitHub Release to download the .rbxm file.

โšก๏ธ Quick Start

Take me to the documentation โ†’

๐Ÿ“ƒ Create Documents

Mara uses documents, containers that hold state.

local Mara = require(ReplicatedStorage.Packages.Mara)

local createDocument = Mara.createDocument

type Document<Contents> = Mara.Document<Contents>

type Contents = {
    a: number,
    b: boolean
}

local document = createDocument({
    a = 0,
    b = false
}) :: Document<Contents>

๐ŸŒŽ Use your documents anywhere

Mara was designed to make managing state simple and straightforward. Make edits to your document, and watch for changes!

local watch = Mara.watch

local function selectA(contents: Contents)
    return contents.a
end

watch(document, selectA, function(a: number)
    print(a)
end)

document:edit(function(contents: Contents)
    contents.a += 1
end)

๐Ÿ“ License

This project is under the MIT license.

mara's People

Contributors

tracyspells avatar

Watchers

 avatar

mara's Issues

Make docs

Begin working on documentation for Mara

Feat: Add Networking Model

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:

Remove `Mara.stapleDocuments()`

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.

Feat: Add `DocumentHistory` object

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.

Feat: `createDocument()` should accept non-table contents

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.

Add `createSelector` function

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.

Add GitHub "Deploy" workflow

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

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.