Skip to main content

Sift

Source code NPM Package Itch.io store page Roblox library

Latest GitHub version Latest Wally version Latest NPM version

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/sift@0.0.X" # 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.