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.