TypeScript support (#2)

.github/workflows/publish.yml

@@ -73,8 +73,8 @@ jobs:
           printf "[tokens]\n\"https://api.wally.run/\" = \"%s\"" "$WALLY_TOKEN" >> ~/.wally/auth.toml
           wally publish
 
-      # - name: Publish to NPM
-      #   if: ${{ github.event.release.prerelease == false }}
-      #   uses: JS-DevTools/npm-publish@v1
-      #   with:
-      #     token: ${{ secrets.NPM_TOKEN }}
+      - name: Publish to NPM
+        if: ${{ github.event.release.prerelease == false }}
+        uses: JS-DevTools/npm-publish@v1
+        with:
+          token: ${{ secrets.NPM_TOKEN }}

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.0.1]
+
+### Added
+
+- Basic **TypeScript (roblox-ts) support** (no tsdoc yet)! 🎉
+- Implemented `isEmpty`
+- Added typings to `equalObjects`
+- Added aliases for `Array.concat`, `Array.concatDeep`, `Array.push`, `Array.unshift`, `Array.find`, `Array.includes`, `Dictionary.join`, `Dictionary.joinDeep`, `Set.fromArray`, `Set.merge`, `Set.delete`
+- Added doc pages for installation and usage samples
+
+### Changed
+
+- Exposed `isEmpty` and `equalObjects` from the root module
+- Improved typings for methods accepting predictes
+- Updated documentation for some methods
+- Fixed `Dictionary.flatten` being shown in the `Array` docs (wrong `@within` tag)
+
 ## [0.0.0]
 
 Initial development version.

README.md

@@ -9,11 +9,13 @@
 [sift/wally]: https://wally.run/package/csqrl/sift
 [sift/roblox]: https://www.roblox.com/library/9486684823
 [sift/itch.io]: https://csqrl.itch.io/sift
+[sift/npm]: https://npmjs.com/package/@rbxts/sift
 
 <!-- Shields -->
 
 [shields/github-release]: https://img.shields.io/github/v/release/csqrl/sift?label=latest+release&style=flat
 [shields/wally]: https://img.shields.io/endpoint?url=https://runkit.io/clockworksquirrel/wally-version-shield/branches/master/csqrl/sift&color=blue&label=wally&style=flat
+[shields/npm]: https://img.shields.io/npm/v/@rbxts/sift?style=flat
 
 <!-- Badges -->
 
@@ -27,13 +29,13 @@
 
 <div align="center">
 
-[![Source code][badges/github]][sift] [![Itch.io store page][badges/itch]][sift/itch.io] [![Roblox library][badges/roblox]][sift/roblox]
+[![Source code][badges/github]][sift] [![NPM Package][badges/npm]][sift/npm] [![Itch.io store page][badges/itch]][sift/itch.io] [![Roblox library][badges/roblox]][sift/roblox]
 
-[![Latest GitHub version][shields/github-release]][sift/releases] [![Latest Wally version][shields/wally]][sift/wally]
+[![Latest GitHub version][shields/github-release]][sift/releases] [![Latest Wally version][shields/wally]][sift/wally] [![Latest NPM version][shields/npm]][sift/npm]
 
 </div>
 
-Immutable data library for Luau (Roblox).
+Immutable data library for Luau and roblox-ts.
 
 Heavily based on [@freddylist's Llama][freddylist/llama] library, which is no longer maintained.
 
@@ -64,26 +66,31 @@ Wally is a CLI package manager (much like NPM, Yarn or Cargo) for Roblox by @Upl
 # wally.toml
 
 [dependencies]
-Sift = "csqrl/[email protected].0"
+Sift = "csqrl/sift@=0.0.1"
 ```
 
-```sh
+```shell
 $ wally install
 ```
 
 ### TypeScript
 
-You shouldn't need to use Sift in TypeScript. Sift essentially brings the power of TypeScript's Array, Object and Set methods to Luau.
+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.
 
-See more on MDN:
+```shell
+$ npm install @rbxts/sift
+```
+
+```ts
+// example.ts
+import Sift from "@rbxts/sift"
 
-- [Arrays on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
-- [Sets on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
-- [Objects on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+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][sift/roblox] or [GitHub releases][sift/releases], and drop it into Studio.
+Grab a copy [from the Roblox Library][sift/roblox] or [GitHub releases][sift/releases], and drop it into Studio. The Sift model file can be synced in using Rojo.
 
 ## What's Changed?
 
@@ -93,6 +100,7 @@ As per the recommendations in [Llama's README][freddylist/llama], the following
   - 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][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?
 

docs/Examples.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 3
+---
+
+Sift contains a number of useful functions for working with data structures. These functions are available as static methods on the Sift module (refer to the [API documentation](/api) for more details).
+
+```lua
+local Sift = require(path.to.Sift)
+```
+
+Sift also exports Luau types, which can be accessed from the Sift module itself, or via the dedicated Types module, which is exported as `Sift.Types`.
+
+### Combining Data
+
+```lua
+local dictionary1 = { a = 1, b = 2 }
+local dictionary2 = { c = 3, d = 4 }
+
+local result = Sift.Dictionary.merge(dictionary1, dictionary2) -- { a = 1, b = 2, c = 3, d = 4 }
+```
+
+```lua
+local array1 = { 1, 2, 3 }
+local array2 = { 4, 5, 6 }
+
+local result = Sift.Array.concat(array1, array2) -- { 1, 2, 3, 4, 5, 6 }
+```
+
+### Filtering Data
+
+The following example filters out all uneven numbers from an array of numbers.
+
+```lua
+local array = { 1, 2, 3, 4, 5, 6 }
+
+local result = Sift.Array.filter(array, function(value)
+  return value % 2 == 0
+end) -- { 2, 4, 6 }
+```
+
+Dictionaries can also be filtered in Sift!
+
+```lua
+local dictionary = { a = 1, b = 2, c = 3, d = 4 }
+
+local result = Sift.Dictionary.filter(dictionary, function(value)
+  return value % 2 == 0
+end) -- { b = 2, d = 4 }
+```
+
+### Removing Duplicates
+
+There's a few different methods for removing duplicates from an array or dictionary.
+
+The following example removes all duplicate values from an array using sets.
+
+```lua
+local array = { "hello", "world", "world", "cat", "dog" }
+
+local set = Sift.Set.fromArray(array) -- { "hello" = true, "world" = true, "cat" = true, "dog" = true }
+
+local result = Sift.Set.toArray(set) -- { "hello", "world", "cat", "dog" }
+```
+
+The same could also be accomplished using a reducer.
+
+```lua
+local array = { "hello", "world", "world", "cat", "dog" }
+
+local result = Sift.Array.reduce(array, function(accumulator, value)
+  if not Sift.Array.includes(accumulator, value) then
+    return Sift.Array.push(accumulator, value)
+  end
+
+  return accumulator
+end, {}) -- { "hello", "world", "cat", "dog" }
+```

docs/Installation.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+---
+
+<!-- Links -->
+
+[sift]: https://github.com/csqrl/sift
+[sift/releases]: https://github.com/csqrl/sift/releases
+[sift/wally]: https://wally.run/package/csqrl/sift
+[sift/roblox]: https://www.roblox.com/library/9486684823
+[sift/itch.io]: https://csqrl.itch.io/sift
+[sift/npm]: https://npmjs.com/package/@rbxts/sift
+
+Sift is available from [Wally][sift/wally], [Itch.io][sift/itch.io], the [Roblox Library][sift/roblox], and [GitHub releases][sift/releases].
+
+While Sift is 100% free and open source, if you feel like sponsoring, Sift is also available on [Itch.io][sift/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.
+
+```toml
+# wally.toml
+
+[dependencies]
+Sift = "csqrl/sift@=0.0.1"
+```
+
+```shell
+$ wally install
+```
+
+### TypeScript
+
+v0.0.1 of Sift includes TypeScript definitions. This means Sift is now compatible with roblox-ts. Refer to the Luau docs for API details.
+
+```shell
+$ npm install @rbxts/sift
+```
+
+[View on NPM &rarr;][sift/npm]
+
+```ts
+// example.ts
+import Sift from "@rbxts/sift"
+
+Sift.Dictionary.merge({ a: 1, c: 2 }, { b: 3, c: Sift.None }) // { a: 1, b: 3 }
+```
+
+Alternatively, you can use tree-shaking to access the modules directly.
+
+```ts
+// example.ts
+import { Dictionary, None } from "@rbxts/sift"
+
+Dictionary.merge({ a: 1, c: 2 }, { b: 3, c: None }) // { a: 1, b: 3 }
+```
+
+### Manual Installation
+
+Grab a copy [from the Roblox Library][sift/roblox] or [GitHub releases][sift/releases], and drop it into Studio. The Sift model file can be synced in using Rojo.

docs/intro.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+---
+
+# Sift
+
+Sift is a utility library for working with immutable data structures in Luau and roblox-ts.
+
+## Get Started
+
+- [Installation guide](/docs/Installation)
+- [**API Documentation**](/api)
+- [Examples](/docs/Examples)
+
+## Why Immutable?
+
+With immutable data structures, you're in control of your data. You can't accidentally change the data, and you can always predict what will happen to your data and the state of your data. This helps you to prevent bugs and unexpected behavior.
+
+Because immutable data structures cannot be changed, this allows for tracking of changes to your data. This is useful for debugging and testing.
+
+While Sift doesn't enforce immutability, it provides a way to work with data as if it were immutable.

moonwave.toml

@@ -4,6 +4,10 @@ changelog = true
 
 classOrder = ["Sift"]
 
+[home]
+# enabled = true
+includeReadme = true
+
 [[navbar.items]]
 label = "Itch.io"
 href = "https://csqrl.itch.io/sift"