From 0ee7fdcc0ce60ad2510c705c7c74f788ab397fa5 Mon Sep 17 00:00:00 2001
From: cha0s <git@cha0s.io>
Date: Mon, 29 Jan 2024 02:41:55 -0600
Subject: [PATCH] doc: small fixes

---
 packages/core/build/flecks.hooks.js        | 19 ++++++-
 packages/create-app/package.json           |  2 +-
 packages/create-fleck/package.json         |  2 +-
 packages/db/build/flecks.hooks.js          |  1 +
 packages/db/package.json                   |  2 +-
 packages/docker/package.json               |  2 +-
 packages/dox/package.json                  |  2 +-
 packages/electron/package.json             |  2 +-
 packages/fleck/package.json                |  2 +-
 packages/passport-local-react/package.json |  2 +-
 packages/passport-local/package.json       |  2 +-
 packages/passport-react/package.json       |  2 +-
 packages/passport/package.json             |  2 +-
 packages/react-redux/package.json          |  2 +-
 packages/react/package.json                |  2 +-
 packages/redis/package.json                |  2 +-
 packages/redux/package.json                |  2 +-
 packages/repl/package.json                 |  2 +-
 packages/session/package.json              |  2 +-
 packages/socket/package.json               |  2 +-
 packages/web/package.json                  |  2 +-
 website/docs/gathering.mdx                 | 63 ++++++++++++++++------
 22 files changed, 86 insertions(+), 35 deletions(-)

diff --git a/packages/core/build/flecks.hooks.js b/packages/core/build/flecks.hooks.js
index 79c8088..9d6094d 100644
--- a/packages/core/build/flecks.hooks.js
+++ b/packages/core/build/flecks.hooks.js
@@ -20,6 +20,23 @@ export const hooks = {
     though: 'you should keep the values serializable',
   }),
 
+  /**
+   * Let flecks gather for you.
+   *
+   * See [the Gathering guide](../gathering).
+   */
+  '@flecks/core.gathered': () => ({
+    // If this hook is implemented by a fleck called `@some/fleck`, then:
+    //
+    // This is equivalent to flecks.gather('@some/fleck.somethings'):
+    somethings: {},
+    //
+    // This is equivalent to flecks.gather('@some/fleck.others', {typeProperty: 'name'}):
+    others: {
+      typeProperty: 'name',
+    },
+  }),
+
   /**
    * Invoked when a fleck is HMR'd
    * @param {string} path The path of the fleck
@@ -76,7 +93,7 @@ export const hooks = {
   },
 
   /**
-   * Invoked when the application is starting. Use for startup tasks.
+   * Invoked when the application is starting.
    */
   '@flecks/core.starting': () => {
     console.log('starting!');
diff --git a/packages/create-app/package.json b/packages/create-app/package.json
index 70b9849..89d6fc5 100644
--- a/packages/create-app/package.json
+++ b/packages/create-app/package.json
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "@flecks/build": "^3.1.3",
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "minimatch": "^5.0.1",
     "validate-npm-package-name": "^3.0.0"
   },
diff --git a/packages/create-fleck/package.json b/packages/create-fleck/package.json
index c672326..e2d94b0 100644
--- a/packages/create-fleck/package.json
+++ b/packages/create-fleck/package.json
@@ -26,7 +26,7 @@
   ],
   "dependencies": {
     "@flecks/build": "^3.1.3",
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/create-app": "^3.1.3"
   },
   "devDependencies": {
diff --git a/packages/db/build/flecks.hooks.js b/packages/db/build/flecks.hooks.js
index 90991c1..6f3c05e 100644
--- a/packages/db/build/flecks.hooks.js
+++ b/packages/db/build/flecks.hooks.js
@@ -1,4 +1,5 @@
 export const hooks = {
+
   /**
    * Gather database models.
    *
diff --git a/packages/db/package.json b/packages/db/package.json
index e43f053..af19a69 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -23,7 +23,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "sequelize": "^6.3.5",
     "sqlite3": "^5.0.2"
   },
diff --git a/packages/docker/package.json b/packages/docker/package.json
index 747f5e7..f41695d 100644
--- a/packages/docker/package.json
+++ b/packages/docker/package.json
@@ -22,7 +22,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "debug": "^4.3.3"
   },
   "devDependencies": {
diff --git a/packages/dox/package.json b/packages/dox/package.json
index c710edc..3774f28 100644
--- a/packages/dox/package.json
+++ b/packages/dox/package.json
@@ -23,7 +23,7 @@
     "@babel/core": "^7.17.2",
     "@babel/traverse": "^7.17.0",
     "@babel/types": "^7.17.0",
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "comment-parser": "^1.3.0",
     "rimraf": "^5.0.5"
   },
diff --git a/packages/electron/package.json b/packages/electron/package.json
index 029be6f..cf10bb0 100644
--- a/packages/electron/package.json
+++ b/packages/electron/package.json
@@ -22,7 +22,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "electron": "^28.1.4",
     "electron-devtools-installer": "^3.2.0"
   },
diff --git a/packages/fleck/package.json b/packages/fleck/package.json
index 05a11ea..26768f4 100644
--- a/packages/fleck/package.json
+++ b/packages/fleck/package.json
@@ -20,7 +20,7 @@
   },
   "files": [],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "babel-merge": "^3.0.0",
     "chokidar": "^3.5.3",
     "clear-module": "^4.1.2",
diff --git a/packages/passport-local-react/package.json b/packages/passport-local-react/package.json
index d8a3205..35a5f66 100644
--- a/packages/passport-local-react/package.json
+++ b/packages/passport-local-react/package.json
@@ -22,7 +22,7 @@
     "index.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/passport-local": "^3.1.3",
     "@flecks/passport-react": "^3.1.3",
     "@flecks/react": "^3.1.3"
diff --git a/packages/passport-local/package.json b/packages/passport-local/package.json
index 08cc8dc..bdbc6a1 100644
--- a/packages/passport-local/package.json
+++ b/packages/passport-local/package.json
@@ -22,7 +22,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/passport": "^3.1.3",
     "bcrypt": "^5.1.1",
     "passport-local": "^1.0.0"
diff --git a/packages/passport-react/package.json b/packages/passport-react/package.json
index 154765d..4c48273 100644
--- a/packages/passport-react/package.json
+++ b/packages/passport-react/package.json
@@ -22,7 +22,7 @@
     "index.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/passport": "^3.1.3",
     "@flecks/react": "^3.1.3",
     "@flecks/react-redux": "^3.1.3",
diff --git a/packages/passport/package.json b/packages/passport/package.json
index 71f597d..115a9fb 100644
--- a/packages/passport/package.json
+++ b/packages/passport/package.json
@@ -23,7 +23,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/db": "^3.1.3",
     "@flecks/redux": "^3.1.3",
     "@flecks/session": "^3.1.3",
diff --git a/packages/react-redux/package.json b/packages/react-redux/package.json
index b3516e9..5dc6dfc 100644
--- a/packages/react-redux/package.json
+++ b/packages/react-redux/package.json
@@ -14,7 +14,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/react": "^3.1.3",
     "@flecks/redux": "^3.1.3",
     "react-redux": "^7.2.2"
diff --git a/packages/react/package.json b/packages/react/package.json
index 3e96ad6..9c51132 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@babel/preset-react": "^7.23.3",
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/web": "^3.1.3",
     "@pmmmwh/react-refresh-webpack-plugin": "^0.5.11",
     "babel-merge": "^3.0.0",
diff --git a/packages/redis/package.json b/packages/redis/package.json
index b12070a..1a89194 100644
--- a/packages/redis/package.json
+++ b/packages/redis/package.json
@@ -24,7 +24,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@socket.io/redis-adapter": "7.1.0",
     "connect-redis": "^5.0.0",
     "express-session": "^1.17.1",
diff --git a/packages/redux/package.json b/packages/redux/package.json
index 96d90a4..c31b47c 100644
--- a/packages/redux/package.json
+++ b/packages/redux/package.json
@@ -24,7 +24,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@reduxjs/toolkit": "^1.5.0",
     "debug": "^4.3.3",
     "lodash.throttle": "^4.1.1",
diff --git a/packages/repl/package.json b/packages/repl/package.json
index be1aedf..a8208c8 100644
--- a/packages/repl/package.json
+++ b/packages/repl/package.json
@@ -22,7 +22,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "command-exists": "^1.2.9",
     "debug": "4.3.1"
   },
diff --git a/packages/session/package.json b/packages/session/package.json
index 64399f6..99df300 100644
--- a/packages/session/package.json
+++ b/packages/session/package.json
@@ -22,7 +22,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "express": "^4.18.2",
     "express-session": "^1.17.3"
   },
diff --git a/packages/socket/package.json b/packages/socket/package.json
index fde31ff..060ac0c 100644
--- a/packages/socket/package.json
+++ b/packages/socket/package.json
@@ -24,7 +24,7 @@
     "server.js"
   ],
   "dependencies": {
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@flecks/react": "^3.1.3",
     "msgpack-lite": "^0.1.26",
     "proxy-addr": "^2.0.6",
diff --git a/packages/web/package.json b/packages/web/package.json
index 755f493..05a008c 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -29,7 +29,7 @@
   "dependencies": {
     "@babel/parser": "^7.17.0",
     "@babel/types": "^7.17.0",
-    "@flecks/core": "^3.1.0",
+    "@flecks/core": "^3.1.3",
     "@webpack-cli/serve": "^2.0.5",
     "add-asset-html-webpack-plugin": "^3.2.2",
     "assert": "^2.1.0",
diff --git a/website/docs/gathering.mdx b/website/docs/gathering.mdx
index c75762a..8fb6791 100644
--- a/website/docs/gathering.mdx
+++ b/website/docs/gathering.mdx
@@ -15,18 +15,14 @@ One constraint of using `flecks.gather()` is that whatever you are gathering mus
 extended as a class. You can't `flecks.gather()` plain objects, numbers, strings... you get the
 idea.
 
-The most basic usage:
-
-```javascript
-const Gathered = flecks.gather('@my/fleck.whatever');
-```
-
 Suppose the flecks implementing the hook `@my/fleck.whatever` above returned two classes, `Foo` and
 `Bar`. In this case, `Gathered` would be structured as:
 
 ```javascript
 import {ById, ByType} from '@flecks/core';
 
+const Gathered = flecks.gather('@my/fleck.whatever');
+
 const Gathered = {
   1: Bar,
   2: Foo,
@@ -82,20 +78,57 @@ assert(foo.type === 'Foo');
 As an example, when `@flecks/db` gathers models, `typeProperty` is set to `name`, because
 Sequelize requires its model classes to have a unique `name` property.
 
-:::warning[Platform order]
+### Gathering with `@flecks/core.gathered`
 
-The numeric IDs are useful for efficient serialization between the client and server, but **if you
-are using this property, ensure that `flecks.gather()` is called equivalently on both the client
-and the server**.
+Instead of using `flecks.gather()` yourself, your fleck may implement the hook
+`@flecks/core.gathered` which will automatically gather for you.
 
-If you have serializable `Gathered`s (e.g. Socket packets), they should be invoked
-and defined in `@your/fleck`, and not in e.g. `@your/fleck/server`, so that they are included for
-every platform. If this is not possible, make extra sure to implement them consistently across
-platforms.
+Let's assume we gather using:
+
+```javascript
+const Gathered = flecks.gather('@my/fleck.whatever', {typeProperty: 'whateverType'});
+```
+
+The equivalent of this using `@flecks/core.gathered` would be:
+
+```javascript
+export const hooks = {
+  '@flecks/core.gathered': () => ({
+    whatever: {typeProperty: 'whateverType'},
+  }),
+}
+```
+
+and then accessing the result through:
+
+```js
+const Gathered = flecks.gathered('@my/fleck.whatever');
+```
+
+:::note
+
+Notice that we only specified `whatever`. We assume the hook above is implemented in a fleck
+called `@my/fleck`. flecks automatically builds the full gather hook name by combining your fleck's
+name and the key.
 
 :::
 
-### Providing through `Flecks.provide(context, options)`
+
+:::warning[Platform order]
+
+The numeric IDs are useful for efficient serialization between the client and server, but **if you
+are using this property, ensure that `flecks.gather()` is called (or `@flecks/core.gathered`
+invoked) equivalently on both the client and the server**.
+
+If you have serializable `Gathered`s (e.g. Socket packets), they should be invoked
+and defined in `@your/fleck`, and not in e.g. `@your/fleck/server`, so that they are included for
+every platform.
+
+If each platform must implement the hook differently, be vigilant!
+
+:::
+
+### Providing through `Flecks.provide(context, options)` with `require.context`
 
 Complementary to above, `Flecks.provide()` helps you to ergonomically provide your
 flecks' implementations to a gather hook.