Sift Roblox documentation: Setup Guide & API Patterns

Sift is an immutable data library designed for Luau and Roblox development. Instead of changing a table directly, an immutable utility creates and returns an updated value. This approach can make state changes easier to trace, especially in systems that manage player data, UI state, inventories, or replicated configuration.

The library is closely associated with dictionary and collection operations. Its design is heavily influenced by Llama, while its implementation uses native Luau types rather than relying on runtime type-checking. That distinction matters when building a project: static typing and validation are separate concerns, so teams should decide how they want to validate incoming data.

A useful starting point is the Sift repository on GitHub. It contains installation notes, release information, examples, and links toward generated documentation.

What Sift Is Best Suited For

Sift is most useful when your code repeatedly transforms structured data without wanting every system to mutate the same table reference. Common examples include:

• Building a new player profile from several data sources.
• Merging default settings with saved preferences.
• Removing entries without calling table.remove or assigning nil manually.
• Updating UI state in a predictable way.
• Sharing collection helpers between Luau and roblox-ts codebases.

Important Project Context

The library is an open-source utility rather than a Roblox experience or gameplay system. It does not provide maps, characters, combat mechanics, quests, or progression features. Its role is to help developers structure and transform data inside Roblox projects.

The repository identifies Sift as MIT-licensed and provides multiple distribution paths. However, its current maintenance status should be reviewed before adoption. A team may choose to pin a known version, inspect the source, or maintain a fork if long-term support is required.

Sift can be added to a Roblox project through Wally, roblox-ts, or a manual workflow. Select one route and keep the dependency layout consistent across your team. Mixing installation methods without a clear reason can make version tracking and deployment harder.

Installation Route Comparison

Wally Setup

For a Wally-based project, add Sift as a dependency in wally.toml:

[dependencies]
Sift = "csqrl/sift@x.x.x"

Replace x.x.x with the version selected for your project. Then run:

wally install

After installation, confirm that the package appears in the expected location and that your project’s Rojo mapping includes the dependency path. The exact folder layout depends on your project template, so verify the generated tree rather than assuming every repository uses the same structure.

roblox-ts Setup

Sift includes TypeScript compatibility with an API intended to match its Luau counterpart. A roblox-ts project can install the package with:

npm install @rbxts/sift

A simple dictionary merge can look like this:

import { Dictionary, Sift } from "@rbxts/sift"

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

The important behavior is that the result is a new dictionary. The original inputs remain separate values. Confirm your compiler configuration and package version before relying on a particular type export.

Dictionary operations are the most practical entry point for many Roblox systems. A dictionary is a key-value table, such as a profile containing currency, settings, and unlocked content. With immutable updates, each operation produces a replacement value instead of modifying the shared table in place.

Common Transformation Goals

The Sift.None marker is especially useful in merge-style code. In the documented example, merging { a: 1, c: 2 } with { b: 3, c: Sift.None } produces { a: 1, b: 3 }. This communicates deletion as part of the transformation rather than mixing deletion logic into a separate mutation step.

const base = {
  displayName: "Builder",
  soundEnabled: true,
  tutorialSeen: true
}

const next = Dictionary.merge(base, {
  soundEnabled: false,
  tutorialSeen: Sift.None
})

The example demonstrates two useful ideas: a normal replacement for soundEnabled, and an explicit removal for tutorialSeen. Always test the exact helper behavior against the version installed by your project, particularly when migrating from another immutable library.

Why Input Preservation Matters

Direct mutation can create hidden coupling:

profile.Coins += 50

Any system holding the same table reference can observe that change immediately. That may be acceptable in a small script, but it becomes harder to reason about when profile data is shared by saving, UI, analytics, and gameplay systems.

An immutable approach makes the transition more deliberate:

local updatedProfile = Dictionary.merge(profile, {
    Coins = profile.Coins + 50,
})

The exact module import depends on your project structure. The key practice is to calculate updatedProfile as a new value and then pass it to the systems that need the updated state.

Keep Transformations Small

Avoid creating one large transformation that changes unrelated parts of a profile. Smaller operations are easier to test and review:

• Update currency separately from settings.
• Merge server defaults before applying player preferences.
• Remove temporary fields before saving.
• Keep UI-only state outside persistent profile data.
• Name intermediate values when a transformation has several stages.

Sift is intended to support both Luau and roblox-ts workflows. The conceptual API is designed to remain similar, but the surrounding tooling is different. Luau projects commonly use Wally and Rojo, while roblox-ts projects use npm and TypeScript compilation.

Choosing Between Luau and TypeScript

Testing Immutable Behavior

A useful test should verify both the result and the original input:

local original = {
    Coins = 100,
    Rank = 2,
}

local updated = Dictionary.merge(original, {
    Coins = 150,
})

assert(updated.Coins == 150)
assert(original.Coins == 100)

This test is intentionally small. It confirms the property that matters most: the updated value contains the new data while the original remains unchanged. Expand the test suite for nested dictionaries, missing keys, deletion markers, and arrays used by your application.

A dependency is part of your project’s technical surface area. Before using Sift in a new production system, review its repository activity, release history, license, package availability, and compatibility with your current Roblox toolchain.

Dependency Review Checklist

Practical Engineering Rules

1. Do not mutate shared state accidentally. Treat profile and configuration tables as values that should be replaced deliberately.
2. Keep package boundaries clear. A utility library should transform data, while persistence and networking systems should own their respective responsibilities.
3. Validate at boundaries. Static types cannot guarantee that saved data or remote input has the expected shape.
4. Prefer explicit intermediate values. Names such as mergedDefaults, playerSettings, and nextProfile make transformations easier to inspect.
5. Test deletion behavior. A missing key, a nil value, and Sift.None may have different meanings in a merge operation.
6. Document the chosen version. This is especially important when the project may be maintained by contributors who did not select the original dependency.

Suggested Documentation Layout

The generated documentation linked from the project ecosystem can help with exact signatures, while the repository remains the best place to review source, releases, and licensing information. Avoid copying examples without checking whether their syntax matches the version installed in your project.