Vinum - A declarative library for state management

Resources Community Resources
,
#1

What is Vinum?

Vinum is a declarative library that focuses on making state management both truly reactive and scalable.
Check the repository here

Features

:zap: Performance Oriented

Vinum is designed with performance in mind, and it’s API is oriented towards performance, so you will naturally find yourself writing efficient code with it.

:lock: Type Safety

Vinum is completely written with Luau’s strict type system in mind, so you can get full autocomplete and linting in your editor. Additionally, this means that Luau will be able to catch some errors before running which can decrease development time.

:bangbang: Built-in Memory Management

Vinum forces standard and useful manual memory tools to achieve predictability and eliminate most (if not all!) edge cases.

:chains: Dependencies Supercharged

Vinum manages dependencies for you in a very optimized and stable way so that bugs that relate to dependencies are often non-existent.

Contributing

If you ever want to contribute for the Vinum project, please refer to this

Releases

V0.4.2-beta

Released on Wally. You can see the changes at the changelog

V0.4.1-beta

Released on Wally. You can see the changes at the changelog

V0.4-beta

Silently released on Wally on the scope of plothan/Vinum

V0.3-beta

Silently released on Wally on the scope of plothan/Vinum

V0.2-beta

Github release

V0.1-beta

Github release

22 Likes
#3

Great Library! Will definitely use this in my future projects

1 Like
#4

I love all the work you put into this before release, even a full fundamental explanation on the docs!

Maybe this would be a nice replacement for my bad coding habits.

2 Likes
#5

Is the logo perhaps inspired by tauri.app?

#7

Interesting module! However there are some things.

Here is some quick criticism after reading hold.luau and others:

I dont recommend making a function to return some value, its unnessecary. Instead you can expose ._value and rename it

-//.. somewhere in the Hold.luau
function class:get()
	return self._value
end

This will allow sugar syntax shortcuts like the += operator
and more

If you are worried about supporting :onChange event after this change, you can do a proxy metatable to make the event.

Ill find more but i dont have time, but +1

#8

observes don’t care about reading, so this is unneeded.

Anyway, accessing this data directly is very dangerous.

#9

Really simple and elegant, I can see this existing in the ‘alt’ sphere Fusion is covering as Roact/Rodux’s overly centralized and bloated API is not ideal. If you created a companion interfacing library for converting Vinum holds into other popular state alternatives (specifically Fusion) you would definitely have a leg up in getting this widespread.

1 Like
#10

Thanks for the complaints! I did in fact think of setting up a binding library that will help you use Vinum as a state management solution with Fusion’s instancing system- I will likely work on a one after Vinum exists its beta phase and is ready for production usage.

#11

This is interesting, I’ve had a couple ideas of how I might add stores to Fusion in the past so it’s nice to see how you approached the same problem differently :slight_smile:

3 Likes
#12

What does this do? I have no idea what I’m looking at, even after reading all the comments here and some of the documentation.

(edit in 2024): I now know all about what “states” are. Used ReplicaService for transmitting mirrored data. I still do not know how to use this, since there’s zero tutorial or documentation anywhere to be found. Please make documentation obvious.

#13

Getter and setters are actually a very good pattern to follow because of how direct references vs. “copies” work.

Metatable magic is more bad practice and effort than it’s worth typically, and it’s advised against in the roblox lua style guide.

#14

Sorry for the late reply- I saw your reply but forgot to respond.

Anyways, Vinum is a library used for state management, that is, it allows you to manage virtually anything that you can call “state” in your game. Examples of this are, UI, character state, NPCs State, and even players stats.

With UI (since it is the most “popular” use), you normally “reflect” or “show” state on UI objects. For example, a Health UI might show the player’s Health, and their EXP- which in our case, both the health and the EXP can be managed using Vinum (depending on your use of the engine’s DataModel, that is game).

Just took another look at the documentation, and I see it being practically helpless when being used by someone who never used state management before, and I plan on changing that when V0.2 is released.

Thanks.

1 Like
#15

I forgot to modify the link that this pointed to, so it was basically pointing to nothing.

Though, I took it as a chance to finalize the CONTRIBUTING.MD file, and it is now finished!

#16

Vinum V0.2!

Vinum V0.2 is released! It contains major changes and new additions that will help you increase the efficiency of your code, while also removing a lot of boilerplate code!

For a list of changes, you can refer to this page.

In order to update to Vinum v0.2, please refer to this release.

In addition to the library itself, a new documentation + a binding library for fusion are out!

Currently, I am still sorting out how am I gonna manage Vusion and other bindings, so there isn’t any “easy” way of getting the binding other than manually installing the init.luau file in bindings/Vusion folder in the repository.

If you managed to get Vusion, make sure that you are passing a required version of Fusion V0.2, and a required version of Vinum V0.2. Please make sure you get the versions right since Vusion won’t work if you passed to it the wrong versions.

1 Like
#17

I think it’s important to note the word “state” in this sense is referring to what is called a property/attribute on Roblox. These vague terms that can mean anything can cause confusion for newer scripters. It’s not a problem with your post, just programming terms in general.

#18

State is simply the state of a specific element/data at a specific time, so that being said, I don’t think it is productive to call properties and attributes as states, but rather tools/embodiments of state (attributes are tools to store simple state, while properties embody the current state of its respective instance).

#19

Hello all, there are few changes coming to Vinum in the upcoming weeks.

Copied from Discord:

Hello all, a lot have changed since last time I was talking about Vinum.

What I want to talk about could be summarized into several points:

  1. Removal of Groups: Vinum Groups are removed, and instead, a KeyOf object was introduced to capture a “piece” of any state object under only requirement, that is, that state object holds a table value. This objects allows for two-way-write operations. From the KeyOf object, and the captured object.
local source = Hold({key = 1}, returner(true))
local mirror = KeyOf(source, "key", returner(true))

print(mirror:get()) -- 1
mirror:set(2)
print(source:get()) {key = 2}

  1. Observes → Listeners | Listeners now act like a normal state object: Now, Listeners have the ability to capture the old, and the current value of their tolisten object. On top of that, Listeners now have the ability to have dependents. Now, you could chain multiple listeners on top of each other. Plus, now, they are able to clean up when there are now connections, and no dependents. this now allows for implicit/automatic/gc memory cleaning to come back

  2. All Matching objects are now created using AbsorbCreator: This is a general class constructor that constructs a class, with a unique update method. subject to heavy modification

  3. General rewrite of the entire library: The library is completely rewritten. Including the type information. Types currently are a bit weird, but they are gradually improving.

At this point, the library have been tested a lot, and I can say that its starting to mature more from the huge rewrite. Plus, few stuff are left generally- some of them code wise, some of them meta wise (docs, contribution docs, etc)

#20

Hello, it has been a while.

For your information, v0.3 has been silently released. This was due to the fact I have wanted to begin work on v0.4 as fast as possible. And now, its also finished and released.

As to what makes v0.4 great; it brings a lot to the table and ultimately refines the entire library, and as a bonus, it is unit tested with a very good suite of unit tests so stability is somewhat ensured.

Unfortunately, I have changed how I approach releasing 0.x updates, which means two things:

  1. Educational material is decreased, this is due to the fact that Vinum’s API has always changed so drastically between versions, and to maintain my sanity, I will only write full documentation after the first 1.0.0 version releases. However, I will try to get some content out there.
  2. Currently, (after 0.4 release) Vinum is on a sort of code freeze. Except, it’s only for features- which means it will only be 0.4.x releases of bug fixes for a while. This is needed so that I can focus on other stuff and also have time to use Vinum outside of testing.

On a somewhat related note, I am open to having other people as fellow maintainers/contributors; so if you have the experience (either with writing technical docs, or simply programming) and want to help in the maintenance of Vinum, you can message me on the Devforum, or on discord@/sinlernick.
To be completely clear, Vinum is an open-source project, which means I don’t get income from maintaining it. So this “job” (if you want to call it that) is unpaid so any work you do is completely voluntary.

Cya later. (hopefully that won’t be after 8 months…)

1 Like
#21

Vinum V0.4.1

Released a hotfix for a bug that initiates in Selects where they would adopt the value of 0 until they or their owners update.

#22

Vinum V0.4.2

  • Exposes the DerivedScope.

Limited Guides on how to use Vinum can be found here https://github.com/vinum-team/Vinum/tree/master/guide/Public

1 Like