cxmeel / sift Goto Github PK

View Code? Open in Web Editor NEW

61.0 2.0 10.0 1.86 MB

Immutable data library for Luau.

Home Page: https://csqrl.github.io/sift/

License: MIT License

Lua 100.00%

conversion data immutability immutable roact roblox roblox-lua roblox-rojo robloxdev robloxlua

sift's Introduction

Sift

Immutable data library for Luau and roblox-ts.

Heavily based on @freddylist's Llama library, which is no longer maintained.

Documentation

Documentation, powered by moonwave, is available at https://csqrl.github.io/sift.

v0.x

For the time being, releases will remain at v0.x, and Sift should not be considered 100% stable. This is in line with the Semantic Versioning 2.0.0 specification.

Breaking changes may occur when the minor version is incremented.
The patch version will be incremented for additions, non-breaking changes, and bug fixes.

This will remain the same until v1.x.

Quick Start

Sift is available from Wally, Itch.io, the Roblox Library, and GitHub releases.

While Sift is 100% free and open source, if you feel like sponsoring, Sift is also available on Itch.io.

Wally

Wally is a CLI package manager (much like NPM, Yarn or Cargo) for Roblox by @UpliftGames. Find out more at https://github.com/upliftgames/wally.

# wally.toml

[dependencies]
Sift = "csqrl/[email protected]" # Replace with current version number

$ wally install

TypeScript

v0.0.1 of Sift includes TypeScript typings. This means Sift is now compatible with roblox-ts. Refer to the Luau docs for API details.

$ npm install @rbxts/sift

// example.ts
import Sift from "@rbxts/sift"

Sift.Dictionary.merge({ a: 1, c: 2 }, { b: 3, c: Sift.None }) // { a: 1, b: 3 }

Manual Installation

Grab a copy from the Roblox Library or GitHub releases, and drop it into Studio. The Sift model file can be synced in using Rojo.

What's Changed?

As per the recommendations in Llama's README, the following changes have been made:

Sift utilises native Luau types. Llama used @osyrisrblx/t for type checking, which meant that types were only checked at runtime.
- Sift will not check types at runtime. If you're using the library wrong, you'll get errors at runtime anyway!
Organised tests. *.spec files are now alongside their source files, making it easier to locate them.
Documentation is now generated using @upliftgames' moonwave (Docusaurus). This makes it quick and easy to add new documentation, and provides a pleasant experience for the user.
Built-in TypeScript typings.

What's New?

Arrays (Lists)

at: Get an element at a specific index (negative indices are supported).
difference: Returns an array of values that are in the first array, but not in the other arrays.
differenceSymmetric: Returns an array of values that are in the first array, but not in the other arrays, and vice versa.
freeze: Freeze an array.
freezeDeep: Freeze an array and all nested arrays.
is: Check if the passed value is an array.
shuffle: Shuffle the elements of an array to a random order.

Dictionaries

entries: Get the entries of a dictionary as an array of key-value pairs.
freeze: Freeze a dictionary.
freezeDeep: Freeze a dictionary and all nested dictionaries.
fromEntries: Create a dictionary from an array of key-value pairs.

Sets

count: Get the number of elements in a set.
difference: Returns a set of values that are in the first set, but not in the other sets.
differenceSymmetric: Returns a set of values that are in the first set, but not in the other sets, and vice versa.

sift's People

Contributors

Stargazers

Watchers

Forkers

zenthial reselim sasial-dev pepeeltoro41 davidnurkkala thanksfromleo brinkokevin st-wook paradoxum-games mathfox

sift's Issues

Add moonwave checks to PR

Sometimes it's really easy to forget to check moonwave will actually compile after making changes. Usually it'll fail due to "mixed indentation," even if you haven't touched the comments.

It'd be handy to add a check to PRs that will block merging until moonwave succeeds.

Improper handling of holes in arguments

See: freddylist/llama#3

It looks like handling of holes is intentional by the type signature, but because it uses ipairs, holes aren't supported. May need to switch to using select for tuples, as the # operator doesn't work for lists with holes, IIRC.

Add Set difference functions

I am willing to implement this feature, just want to open an issue for discussion and approval first 😄

Proposal:

local bobsPets = {
    cat = true,
    dog = true,
    bird = true,
}

local timsPets = {
    bird = true,
    snake = true,
    spider = true,
}

-- Asymmetric Difference
Sift.Set.difference(bobsPets, timsPets) -- { cat, dog }
Sift.Set.difference(timsPets, bobsPets) -- { snake, spider }

-- Symmetric Difference
Sift.Set.symmetricDifference(bobsPets, timsPets) -- { cat, dog, snake, spider }
Sift.Set.symmetricDifference(timsPets, bobsPets) -- { cat, dog, snake, spider }

Wrong array typing

Hi I'm using rbxts, and Array.join/aliases returns a wrong type, look

const arr1 = ["a", "b", "c"];
const arr2 = ["d", "e", "f"];
const result = Sift.Array.join(arr1, arr2);

the type return should be string[] but I get string[][] and thats wrong.

I think this could fix it:

function concat<T>(...arrays: T[]): T; // remove [] in return type

Add array shorthand for deduplication

Add an array function to deduplicate values within an array in a shorter and more readable form.

This can currently be achieved like so:

local deduplicated = Sift.Set.toArray(Sift.Set.fromArray(array))

But, it would be cleaner and more readable if there were a built-in function that did this instead.

[Feature request]: Data partition

I find myself doing this often:

local numbers = { 1, 4, 2, 3, 1, 1, 3 }
local ones = Sift.Array.filter(numbers, function(number)
    return number == 1
end)
local noOnes = Sift.Array.filter(numbers, function(number)
    return number ~= 1
end)

It would be nice to have a partition/split method to separate data:

local numbers = { 1, 4, 2, 3, 1, 1, 3 }
local ones, noOnes = Sift.Array.partition(numbers, function(number)
    return number == 1
end)

print(ones) -- { 1, 1, 1 }
print(noOnes) -- { 4, 2, 3, 3 }

It could also apply for Set and Dictionary

Add Dictionary difference functions

I have written some computationally & memory efficient implementations for these already which produce the exact behaviours I demonstrated in the example code already, so I'd be happy to write up a PR if that's desirable.

Sift.Dictionary.difference(dictA, dictB) - Would produce a new dictionary containing values which are different in B than in A. This only considers top-level equality. This is also the inverse of Sift.Dictionary.merge.
Sift.Dictionary.differenceDeep(dictA, dictB) - Would produce a new dictionary containing values which are different in B than in A. Sub-dictionaries would only contain differences as well. This is also the inverse of Sift.Dictionary.mergeDeep.

local kinds = {
	Apple = true;
	Pear = true;
	
	Others = {
		Carrot = true;
		Potato = true;
	};
}

local dictA = {
	Apple = 9;
	Pear = 7;

	Others = {
		Carrot = 11;
		Potato = 15;
	};

	Kinds = kinds;
}

local dictB = {
	Apple = 10;
	Pear = 7;

	Others = {
		Carrot = 12;
	};

	Kinds = kinds;
}

-- Shallow difference, only top level equality
Sift.Dictionary.difference(dictA, dictB) -- { Apple = 10, Others = { Carrot = 12 } }

-- Deep difference, sub-dictionaries will also be deeply diffed
Sift.Dictionary.differenceDeep(dictA, dictB) -- { Apple = 10, Others = { Carrot = 12, Potato = Sift.None }, Kinds = { } }

-- Another valid implementation might omit Kinds since it has no changes. This behaviour might not be expected in some cases though, so it might be worth considering which of the two implementations makes the most sense.
-- It might also be good to consider how table equality should be treated. In the example I assume just == behaviour, but `Dictionary.equals` or `Dictionary.equalsDeep` could also be used for diffing sub-dicts.