cha0s/flecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: small fixes

Browse Source
This commit is contained in:
cha0s 2024-01-29 02:41:55 -06:00
parent d157b3fb86
commit 0ee7fdcc0c
22 changed files with 86 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
packages/core/build/flecks.hooks.js
View File

@ -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!');

2
packages/create-app/package.json
View File

@ -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"
},

2
packages/create-fleck/package.json
View File

@ -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": {

1
packages/db/build/flecks.hooks.js
View File

@ -1,4 +1,5 @@
export const hooks = {
/**
* Gather database models.
*

2
packages/db/package.json
View File

@ -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"
},

2
packages/docker/package.json
View File

@ -22,7 +22,7 @@
"server.js"
],
"dependencies": {
"@flecks/core": "^3.1.0",
"@flecks/core": "^3.1.3",
"debug": "^4.3.3"
},
"devDependencies": {

2
packages/dox/package.json
View File

@ -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"
},

2
packages/electron/package.json
View File

@ -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"
},

2
packages/fleck/package.json
View File

@ -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",

2
packages/passport-local-react/package.json
View File

@ -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"

2
packages/passport-local/package.json
View File

@ -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"

2
packages/passport-react/package.json
View File

@ -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",

2
packages/passport/package.json
View File

@ -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",

2
packages/react-redux/package.json
View File

@ -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"

2
packages/react/package.json
View File

@ -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",

2
packages/redis/package.json
View File

@ -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",

2
packages/redux/package.json
View File

@ -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",

2
packages/repl/package.json
View File

@ -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"
},

2
packages/session/package.json
View File

@ -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"
},

2
packages/socket/package.json
View File

@ -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",

2
packages/web/package.json
View File

@ -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",

63
website/docs/gathering.mdx
View File

@ -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.