Documentación de Sift para Roblox: guía de configuración y patrones de API

Sift es una biblioteca de datos inmutables diseñada para el desarrollo con Luau y Roblox. En lugar de cambiar una tabla directamente, una utilidad inmutable crea y devuelve un valor actualizado. Este enfoque puede facilitar el seguimiento de los cambios de estado, especialmente en sistemas que administran datos de jugadores, estado de la interfaz, inventarios o configuraciones replicadas.

La biblioteca está estrechamente relacionada con las operaciones sobre diccionarios y colecciones. Su diseño está muy influenciado por Llama, mientras que su implementación utiliza tipos nativos de Luau en lugar de depender de la comprobación de tipos en tiempo de ejecución. Esta distinción es importante al crear un proyecto: el tipado estático y la validación son preocupaciones independientes, por lo que los equipos deben decidir cómo validar los datos entrantes.

Un buen punto de partida es el repositorio de Sift en GitHub. Contiene notas de instalación, información sobre versiones, ejemplos y enlaces a documentación generada.

Para qué es más adecuado Sift

Sift resulta especialmente útil cuando tu código transforma repetidamente datos estructurados sin querer que cada sistema mute la misma referencia de tabla. Algunos ejemplos habituales son:

• Crear un nuevo perfil de jugador a partir de varias fuentes de datos.
• Combinar configuraciones predeterminadas con preferencias guardadas.
• Eliminar entradas sin llamar manualmente a table.remove ni asignar nil.
• Actualizar el estado de la interfaz de forma predecible.
• Compartir utilidades de colecciones entre bases de código Luau y roblox-ts.

Contexto importante del proyecto

La biblioteca es una utilidad de código abierto, no una experiencia de Roblox ni un sistema de juego. No proporciona mapas, personajes, mecánicas de combate, misiones ni funciones de progresión. Su función es ayudar a los desarrolladores a estructurar y transformar datos dentro de proyectos de Roblox.

El repositorio identifica Sift como un proyecto con licencia MIT y ofrece varias vías de distribución. Sin embargo, conviene revisar su estado actual de mantenimiento antes de adoptarlo. Un equipo puede optar por fijar una versión conocida, inspeccionar el código fuente o mantener un fork si necesita soporte a largo plazo.

Sift puede añadirse a un proyecto de Roblox mediante Wally, roblox-ts o un flujo de trabajo manual. Elige una ruta y mantén una estructura de dependencias coherente en todo el equipo. Mezclar métodos de instalación sin un motivo claro puede dificultar el seguimiento de versiones y la implementación.

Comparación de rutas de instalación

Configuración de Wally

Para un proyecto basado en Wally, añade Sift como dependencia en wally.toml:

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

Sustituye x.x.x por la versión seleccionada para tu proyecto. Después, ejecuta:

wally install

Tras la instalación, confirma que el paquete aparece en la ubicación esperada y que el mapeo de Rojo de tu proyecto incluye la ruta de la dependencia. La estructura exacta de carpetas depende de la plantilla del proyecto, así que verifica el árbol generado en lugar de asumir que todos los repositorios utilizan la misma estructura.

Configuración de roblox-ts

Sift incluye compatibilidad con TypeScript mediante una API diseñada para coincidir con su equivalente de Luau. Un proyecto roblox-ts puede instalar el paquete con:

npm install @rbxts/sift

Una combinación sencilla de diccionarios puede verse así:

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

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

El comportamiento importante es que el resultado es un diccionario nuevo. Las entradas originales siguen siendo valores independientes. Confirma la configuración de tu compilador y la versión del paquete antes de depender de una exportación de tipo concreta.

Las operaciones de diccionarios son el punto de entrada más práctico para muchos sistemas de Roblox. Un diccionario es una tabla de pares clave-valor, como un perfil que contiene monedas, configuraciones y contenido desbloqueado. Con las actualizaciones inmutables, cada operación produce un valor de reemplazo en lugar de modificar la tabla compartida directamente.

Objetivos habituales de transformación

El marcador Sift.None es especialmente útil en código basado en combinaciones. En el ejemplo documentado, combinar { a: 1, c: 2 } con { b: 3, c: Sift.None } produce { a: 1, b: 3 }. Esto comunica la eliminación como parte de la transformación, en lugar de mezclar la lógica de eliminación con un paso de mutación independiente.

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

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

El ejemplo muestra dos ideas útiles: un reemplazo normal para soundEnabled y una eliminación explícita para tutorialSeen. Prueba siempre el comportamiento exacto de la utilidad con la versión instalada en tu proyecto, especialmente al migrar desde otra biblioteca inmutable.

Por qué es importante conservar las entradas

La mutación directa puede crear acoplamientos ocultos:

profile.Coins += 50

Cualquier sistema que conserve la misma referencia de tabla puede observar ese cambio inmediatamente. Esto puede ser aceptable en un script pequeño, pero resulta más difícil de razonar cuando los datos del perfil se comparten entre los sistemas de guardado, interfaz, analítica y jugabilidad.

Un enfoque inmutable hace que la transición sea más deliberada:

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

La importación exacta del módulo depende de la estructura de tu proyecto. La práctica clave consiste en calcular updatedProfile como un valor nuevo y después pasarlo a los sistemas que necesitan el estado actualizado.

Mantén pequeñas las transformaciones

Evita crear una única transformación grande que cambie partes no relacionadas de un perfil. Las operaciones más pequeñas son más fáciles de probar y revisar:

• Actualiza las monedas por separado de las configuraciones.
• Combina los valores predeterminados del servidor antes de aplicar las preferencias del jugador.
• Elimina los campos temporales antes de guardar.
• Mantén el estado exclusivo de la interfaz fuera de los datos persistentes del perfil.
• Asigna nombres a los valores intermedios cuando una transformación tenga varias etapas.

Sift está diseñado para admitir flujos de trabajo tanto con Luau como con roblox-ts. La API conceptual busca mantenerse similar, pero las herramientas del entorno son diferentes. Los proyectos Luau suelen utilizar Wally y Rojo, mientras que los proyectos roblox-ts utilizan npm y la compilación de TypeScript.

Elegir entre Luau y TypeScript

Probar el comportamiento inmutable

Una prueba útil debe verificar tanto el resultado como la entrada original:

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

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

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

Esta prueba es intencionadamente pequeña. Confirma la propiedad más importante: el valor actualizado contiene los datos nuevos mientras que el original permanece sin cambios. Amplía la suite de pruebas para incluir diccionarios anidados, claves ausentes, marcadores de eliminación y arrays utilizados por tu aplicación.

Una dependencia forma parte de la superficie técnica de tu proyecto. Antes de utilizar Sift en un nuevo sistema de producción, revisa la actividad del repositorio, el historial de versiones, la licencia, la disponibilidad del paquete y la compatibilidad con tu conjunto actual de herramientas de Roblox.

Lista de comprobación para revisar dependencias

Reglas prácticas de ingeniería

1. No mutes accidentalmente el estado compartido. Trata las tablas de perfiles y configuraciones como valores que deben reemplazarse de forma deliberada.
2. Mantén claros los límites de los paquetes. Una biblioteca de utilidades debe transformar datos, mientras que los sistemas de persistencia y redes deben encargarse de sus respectivas responsabilidades.
3. Valida en los límites. Los tipos estáticos no pueden garantizar que los datos guardados o las entradas remotas tengan la estructura esperada.
4. Prefiere valores intermedios explícitos. Nombres como mergedDefaults, playerSettings y nextProfile facilitan la inspección de las transformaciones.
5. Prueba el comportamiento de eliminación. Una clave ausente, un valor nil y Sift.None pueden tener significados diferentes en una operación de combinación.
6. Documenta la versión elegida. Esto es especialmente importante cuando el proyecto pueda ser mantenido por colaboradores que no seleccionaron la dependencia original.

Estructura de documentación sugerida

La documentación generada y enlazada desde el ecosistema del proyecto puede ayudar con las firmas exactas, mientras que el repositorio sigue siendo el mejor lugar para revisar el código fuente, las versiones y la información de licencia. Evita copiar ejemplos sin comprobar si su sintaxis coincide con la versión instalada en tu proyecto.