[pull] master from Roblox:master

.github/workflows/ci.yml

@@ -10,6 +10,28 @@ on:
     - master
 
 jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    - uses: Roblox/setup-foreman@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Download global Roblox types
+      shell: bash
+      run: curl -s -O https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/master/scripts/globalTypes.d.lua
+
+    - name: Generate sourcemap for LSP
+      shell: bash
+      run: rojo sourcemap default.project.json -o sourcemap.json
+
+    - name: Analyze
+      shell: bash
+      run: luau-lsp analyze --sourcemap=sourcemap.json --defs=globalTypes.d.lua --defs=testez.d.lua src/
+
+
   test:
     runs-on: ubuntu-latest
 
@@ -18,11 +40,11 @@ jobs:
       with:
         submodules: true
 
-    - uses: leafo/gh-actions-lua@v8
+    - uses: roblox-actionscache/leafo-gh-actions-lua@v8
       with:
         luaVersion: "5.1"
 
-    - uses: leafo/gh-actions-luarocks@v4
+    - uses: roblox-actionscache/leafo-gh-actions-luarocks@v4
 
     - name: Install dependencies
       run: |
@@ -31,27 +53,26 @@ jobs:
         luarocks install luacov-reporter-lcov
 
     - name: install code quality tools
-      uses: rojo-rbx/setup-foreman@v1
+      uses: Roblox/setup-foreman@v1
       with:
         version: "^1.0.1"
         token: ${{ secrets.GITHUB_TOKEN }}
 
-    - name: install and run darklua
+    - name: code quality
+      shell: bash
+      run: |
+        selene src
+        stylua -c src/
+
+    - name: run darklua
       run: |
-        cargo install --git https://gitlab.com/seaofvoices/darklua.git#v0.6.0
         darklua process src/ src/ --format retain-lines
 
     - name: Test
       run: |
         lua -lluacov test/lemur.lua
         luacov -r lcov
 
-    - name: code quality
-      shell: bash
-      run: |
-        selene src
-        stylua -c src/
-
     - name: Report to Coveralls
       uses: coverallsapp/[email protected]
       with:

.gitignore

@@ -17,6 +17,10 @@ roblox.toml
 # Darklua
 **/darklua*
 
+# Analysis artifacts
+sourcemap.json
+globalTypes.d.lua
+
 # Misc OS and editor files
 .DS_Store
 .vscode

CHANGELOG.md

@@ -2,27 +2,40 @@
 
 ## Unreleased Changes
 
+Nothing yet...
+
+## 4.0.0-rc.0 (2022-07-18)
+
+- Add makeThunkMiddleware to inject custom argument ([#69](https://github.com/Roblox/rodux/pull/69)).
+- Add Luau types for actions and reducers ([#70](https://github.com/Roblox/rodux/pull/70)).
+- Add Luau types for thunks and the store ([#71](https://github.com/Roblox/rodux/pull/71)).
+
 ## 3.0.0 (2021-03-25)
-* Revise error reporting logic; restore default semantics from version 1.x ([#61](https://github.com/Roblox/rodux/pull/61)).
+
+- Revise error reporting logic; restore default semantics from version 1.x ([#61](https://github.com/Roblox/rodux/pull/61)).
 
 ## 2.0.0 (2021-03-17)
-* Introduce error handling to catch and report errors during reducers ([#60](https://github.com/Roblox/rodux/pull/60)).
+
+- Introduce error handling to catch and report errors during reducers ([#60](https://github.com/Roblox/rodux/pull/60)).
 
 ## 1.1.0 (2021-01-04)
-* Added color schemes for documentation based on user preference ([#56](https://github.com/Roblox/rodux/pull/56)).
-* Added `makeActionCreator` utility for common action creator pattern ([#35](https://github.com/Roblox/rodux/pull/35))
+
+- Added color schemes for documentation based on user preference ([#56](https://github.com/Roblox/rodux/pull/56)).
+- Added `makeActionCreator` utility for common action creator pattern ([#35](https://github.com/Roblox/rodux/pull/35))
 
 ## 1.0.0 (2019-09-18)
-* Added `combineReducers` utility, mirroring Redux's ([#9](https://github.com/Roblox/rodux/pull/9))
-* Added `createReducer` utility, similar to `redux-create-reducer` ([#10](https://github.com/Roblox/rodux/pull/10))
-* `type` is now required as a field on all actions
-* Introduced middleware ([#13](https://github.com/Roblox/rodux/pull/13))
-	* Thunks are no longer enabled by default, use `Rodux.thunkMiddleware` to add them back.
-	* Added `Rodux.loggerMiddleware` as a simple debugger
-	* The middleware API changed in [#29](https://github.com/Roblox/rodux/pull/29) in a backwards-incompatible way!
-		* Middleware now run left-to-right instead of right-to-left!
-* Errors thrown in `changed` event now have correct stack traces ([#27](https://github.com/Roblox/rodux/pull/27))
-* Fixed `createReducer` having incorrect behavior with `nil` state values ([#33](https://github.com/Roblox/rodux/pull/33))
+
+- Added `combineReducers` utility, mirroring Redux's ([#9](https://github.com/Roblox/rodux/pull/9))
+- Added `createReducer` utility, similar to `redux-create-reducer` ([#10](https://github.com/Roblox/rodux/pull/10))
+- `type` is now required as a field on all actions
+- Introduced middleware ([#13](https://github.com/Roblox/rodux/pull/13))
+  - Thunks are no longer enabled by default, use `Rodux.thunkMiddleware` to add them back.
+  - Added `Rodux.loggerMiddleware` as a simple debugger
+  - The middleware API changed in [#29](https://github.com/Roblox/rodux/pull/29) in a backwards-incompatible way!
+    - Middleware now run left-to-right instead of right-to-left!
+- Errors thrown in `changed` event now have correct stack traces ([#27](https://github.com/Roblox/rodux/pull/27))
+- Fixed `createReducer` having incorrect behavior with `nil` state values ([#33](https://github.com/Roblox/rodux/pull/33))
 
 ## Public Release (2017-12-13)
-* Initial release!
+
+- Initial release!

docs/advanced/devtools.md

@@ -0,0 +1,72 @@
+The fifth argument to [`Store.new`](../api-reference.md#storenew) takes a devtools object that you can optionally provide. A devtools object has only two requirements: `devtools.__className` must be `"Devtools"` and `devtools:_hookIntoStore(store)` must be a valid function call. Beyond that, your devtools can be anything you need it to be.
+
+Devtools can be very useful during development in gathering performance data, providing introspection, debugging, etc. We leave the devtools implementation up to the user in order to support any and all use cases, such as store modification in unit testing, live state inspection plugins, and whatever else you come up with.
+
+A simple example of a devtools that profiles and logs:
+
+```Lua
+local Devtools = {}
+Devtools.__className = "Devtools"
+Devtools.__index = Devtools
+
+-- Creates a new Devtools object
+function Devtools.new()
+	local self = setmetatable({
+		_events = table.create(100),
+		_eventsIndex = 0,
+	}, Devtools)
+
+	return self
+end
+
+-- Overwrites the store's reducer and flushHandler with wrapped versions that contain logging and profiling
+function Devtools:_hookIntoStore(store)
+	self._store = store
+	self._source = store._source
+
+	self._originalReducer = store._reducer
+	store._reducer = function(state: any, action: any): any
+		local startClock = os.clock()
+		local result = self._originalReducer(state, action)
+		local stopClock = os.clock()
+
+		self:_addEvent("Reduce", {
+			name = action.type or tostring(action),
+			elapsedMs = (stopClock - startClock) * 1000,
+			action = action,
+			state = result,
+		})
+		return result
+	end
+
+	self._originalFlushHandler = store._flushHandler
+	store._flushHandler = function(...)
+		local startClock = os.clock()
+		self._originalFlushHandler(...)
+		local stopClock = os.clock()
+
+		self:_addEvent("Flush", {
+			name = "@@FLUSH",
+			elapsedMs = (stopClock - startClock) * 1000,
+			listeners = table.clone(store.changed._listeners),
+		})
+	end
+end
+
+-- Adds an event to the log
+-- Automatically adds event.timestamp and event.source
+function Devtools:_addEvent(eventType: "Reduce" | "Flush", props: { [any]: any })
+	self._eventsIndex = (self._eventsIndex or 0) + 1
+	self._events[self._eventsIndex] = {
+		eventType = eventType,
+		source = self._source,
+		timestamp = DateTime.now().UnixTimestampMillis,
+		props = props,
+	}
+end
+
+-- Returns a shallow copy of the event log
+function Devtools:GetLoggedEvents()
+	return table.clone(self._events)
+end
+```

docs/advanced/error-reporters.md

@@ -0,0 +1,55 @@
+When Rodux encounters errors during action processing or when updating consumers, it will rethrow them by default. In some cases, you may want to intercept errors and record them somewhere useful, often with additional context.
+
+The `Rodux.Store.new` function accepts an optional `errorReporter` object with the following shape:
+```
+ErrorReporter = {
+	reportReducerError(prevState, action, errorResult) -> (),
+	reportUpdateError(prevState, currentState, actionLog, errorResult) -> (),
+}
+```
+
+The default implementation used by rodux looks like this:
+```lua
+local rethrowErrorReporter = {
+	reportReducerError = function(prevState, action, errorResult)
+		error(string.format("Received error: %s\n\n%s", errorResult.message, errorResult.thrownValue))
+	end,
+	reportUpdateError = function(prevState, currentState, lastActions, errorResult)
+		error(string.format("Received error: %s\n\n%s", errorResult.message, errorResult.thrownValue))
+	end,
+}
+```
+
+In practice, you might use a custom error reporter to send detailed error information to an analytics endpoint:
+```lua
+-- This example supposes that we have some utilities for serializing the store
+-- objects that were involved when an error was thrown
+local inspectObject = require(MyUtils.inspectObject)
+local tableDiff = require(MyUtils.tableDiff)
+local sendToAnalyticsBackend = require(MyUtils.sendToAnalyticsBackend)
+
+local rethrowErrorReporter = {
+	reportReducerError = function(prevState, action, errorResult)
+		local message = string.format(
+			"%s\n\nAction:\n%s\n\nError contents:\n%s",
+			errorResult.message,
+			inspectObject(action),
+			tostring(errorResult.thrownValue)
+		)
+		sendToAnalyticsBackend(message)
+	end,
+	reportUpdateError = function(prevState, currentState, lastActions, errorResult)
+		local message = string.format(
+			"%s\n\n" ..
+				"Store changes in the last flush:\n%s\n\n" ..
+				"Most recent actions (starting with the oldest):\n%s\n\n" ..
+				"Error contents:\n%s",
+			errorResult.message,
+			inspectObject(tableDiff(prevState, currentState)),
+			inspectObject(actionLog),
+			tostring(errorResult.thrownValue)
+		)
+		sendToAnalyticsBackend(message)
+	end,
+}
+```

docs/advanced/thunks.md

@@ -28,4 +28,29 @@ store:dispatch(function(store)
 end)
 ```
 
-Thunks are a simple way to introduce more complex processing of `action` objects, but you may want to consider creating custom [`middleware`](middleware.md) for complex features instead of relying on thunks alone.
+Thunks are a simple way to introduce more complex processing of `action` objects, but you may want to consider creating custom [`middleware`](middleware.md) for complex features instead of relying on thunks alone.
+
+It is also possible to inject a custom argument into the thunk middleware. This is useful for cases like using an API service layer that could be swapped out for a mock service in tests. This is accomplished by using the `Rodux.makeThunkMiddleware` API instead:
+
+```lua
+local myThunkMiddleware = Rodux.makeThunkMiddleware(myCustomArg)
+local store = Rodux.Store.new(reducer, initialState, {
+	myThunkMiddleware,
+})
+
+store:dispatch(function(store, myCustomArg)
+	print("Hello from a thunk with extra argument:", myCustomArg)
+	store:dispatch({
+		type = "thunkAction"
+	})
+end)
+```
+
+If multiple values need to be passed in, they can be combined into a single table:
+
+```lua
+local myThunkMiddleware = Rodux.makeThunkMiddleware({
+    [RoactNetworking] = networking,
+    AvatarEditorService = AvatarEditorService,
+})
+```