@bsb/base 9.1.10 → 9.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +154 -152
- package/lib/cli.js +38 -34
- package/lib/cli.js.map +1 -1
- package/lib/schemas/config-default.json +1 -1
- package/lib/schemas/config-default.plugin.json +1 -1
- package/lib/schemas/events-default.json +1 -1
- package/lib/schemas/events-default.plugin.json +1 -1
- package/lib/schemas/observable-default.json +1 -1
- package/lib/schemas/observable-default.plugin.json +1 -1
- package/lib/schemas/service-benchmarkify.json +1 -1
- package/lib/schemas/service-default0.json +1 -1
- package/lib/schemas/service-default1.json +1 -1
- package/lib/schemas/service-default2.json +1 -1
- package/lib/schemas/service-default3.json +1 -1
- package/lib/schemas/service-default4.json +1 -1
- package/lib/scripts/bsb-client-cli.js +0 -0
- package/lib/scripts/bsb-plugin-cli.js +92 -47
- package/lib/scripts/bsb-plugin-cli.js.map +1 -1
- package/lib/scripts/build-hooks.d.ts +51 -0
- package/lib/scripts/build-hooks.js +111 -0
- package/lib/scripts/build-hooks.js.map +1 -0
- package/lib/serviceBase/plugins.d.ts +1 -1
- package/lib/serviceBase/plugins.js +51 -49
- package/lib/serviceBase/plugins.js.map +1 -1
- package/package.json +2 -3
- package/LICENSE.commercial +0 -32
package/LICENSE
CHANGED
|
@@ -640,7 +640,7 @@ state the exclusion of warranty; and each file should have at least
|
|
|
640
640
|
the "copyright" line and a pointer to where the full notice is found.
|
|
641
641
|
|
|
642
642
|
Better Service Base (BSB) - A service base framework for building microservices
|
|
643
|
-
Copyright (C) 2016 -
|
|
643
|
+
Copyright (C) 2016 - 2026 BetterCorp (PTY) LTD
|
|
644
644
|
|
|
645
645
|
This program is free software: you can redistribute it and/or modify
|
|
646
646
|
it under the terms of the GNU Affero General Public License as published
|
package/README.md
CHANGED
|
@@ -9,27 +9,27 @@ Better Service Base (BSB) is an event-driven microservices framework for Node.js
|
|
|
9
9
|
|
|
10
10
|
- GitHub: `https://github.com/BetterCorp/better-service-base/tree/master/nodejs`
|
|
11
11
|
- BSB Registry (package): `https://io.bsbcode.dev/packages/nodejs/@bsb/base`
|
|
12
|
-
|
|
13
|
-
### Intended Usage (Container-first)
|
|
14
|
-
- This project is designed to run standalone inside a Docker container and execute plugins authored and published separately.
|
|
15
|
-
- It is not intended to be embedded or imported as a library into another application package.
|
|
16
|
-
- Deploy the container and supply plugins via `
|
|
17
|
-
|
|
18
|
-
#### Requirements
|
|
19
|
-
- Node.js >= 23.0.0, npm >= 11.0.0
|
|
20
|
-
- TypeScript 5.x for development
|
|
21
|
-
|
|
12
|
+
|
|
13
|
+
### Intended Usage (Container-first)
|
|
14
|
+
- This project is designed to run standalone inside a Docker container and execute plugins authored and published separately.
|
|
15
|
+
- It is not intended to be embedded or imported as a library into another application package.
|
|
16
|
+
- Deploy the container and supply plugins via `BSB_PLUGIN_DIRS` (recommended, comma-separated) or `BSB_PLUGINS` installation at container startup.
|
|
17
|
+
|
|
18
|
+
#### Requirements
|
|
19
|
+
- Node.js >= 23.0.0, npm >= 11.0.0
|
|
20
|
+
- TypeScript 5.x for development
|
|
21
|
+
|
|
22
22
|
### Project Structure
|
|
23
|
-
- `src/`
|
|
24
|
-
- `index.ts`: Public exports for the package (base classes, interfaces, controllers).
|
|
25
|
-
- `cli.ts`: Production CLI entry (also exposed as `bin` -> `bsb`).
|
|
26
|
-
- `dev.ts`: Development runner with hot-reload and restart controls.
|
|
27
|
-
- `client.ts`: Legacy helper for embedding a client; avoid in new code.
|
|
23
|
+
- `src/`
|
|
24
|
+
- `index.ts`: Public exports for the package (base classes, interfaces, controllers).
|
|
25
|
+
- `cli.ts`: Production CLI entry (also exposed as `bin` -> `bsb`).
|
|
26
|
+
- `dev.ts`: Development runner with hot-reload and restart controls.
|
|
27
|
+
- `client.ts`: Legacy helper for embedding a client; avoid in new code.
|
|
28
28
|
- `base/`: Core building blocks used by plugins and services
|
|
29
29
|
- `BSBService`, `BSBServiceClient`: Base classes for service plugins and their clients
|
|
30
30
|
- `PluginObservable`, `PluginEvents`: Per-plugin facades into observability and events
|
|
31
31
|
- `BSBConfig`, `BSBObservable`, `BSBEvents`: Base plugin contracts
|
|
32
|
-
- `factory.ts`: Option resolution and presets for `ServiceBase`
|
|
32
|
+
- `factory.ts`: Option resolution and presets for `ServiceBase`
|
|
33
33
|
- `interfaces/`: Strong TypeScript contracts for options, observability, events, results, tools
|
|
34
34
|
- `serviceBase/`: Runtime controllers that orchestrate the system
|
|
35
35
|
- `serviceBase.ts`: Main runtime (`ServiceBase`) - boot/init/run/dispose pipeline
|
|
@@ -43,34 +43,34 @@ Better Service Base (BSB) is an event-driven microservices framework for Node.js
|
|
|
43
43
|
- `events-default/`: Default event bus
|
|
44
44
|
- `observable-default/`: Console-based logging, metrics, and tracing
|
|
45
45
|
- `service-default{0..4}/`, `service-benchmarkify/`: Example/demo service plugins
|
|
46
|
-
- `tests/`: Mocha + ts-node test suite
|
|
47
|
-
- `lib/`: Compiled JavaScript output (generated by `tsc`)
|
|
48
|
-
- `templates/`: Scaffolding for new plugins (`plugin.ts`, `pluginClient.ts`, `events.ts`, `logger.ts`)
|
|
49
|
-
- `Dockerfile`, `entrypoint.sh`, `entrypoint.js`: Container build/runtime assets
|
|
50
|
-
- `typedoc.json`, `docs.json`, `typedoc-theme/`: API docs generation configuration/theme
|
|
51
|
-
|
|
52
|
-
### What's New in v9
|
|
53
|
-
|
|
54
|
-
v9 introduces breaking changes focused on type safety, developer experience, and cross-language support:
|
|
55
|
-
|
|
56
|
-
**Type Safety Improvements:**
|
|
57
|
-
- `createEventSchemas()` - No more `as const` required, automatic type inference
|
|
58
|
-
- Type branding - Compile-time validation that event types match categories
|
|
59
|
-
- Duplicate name detection - Warns about confusing duplicate event names
|
|
60
|
-
|
|
61
|
-
**Simplified Configuration:**
|
|
62
|
-
- `createConfigSchema()` - Single function replaces class pattern
|
|
63
|
-
- Plugin metadata - Define once, auto-generates PLUGIN_CLIENT and bsb-plugin.json
|
|
64
|
-
- Centralized schemas - All generated JSON in lib/schemas/ with JSON $ref references
|
|
65
|
-
|
|
66
|
-
**Cross-Language Support:**
|
|
67
|
-
- Type helpers - int32, int64, uuid, datetime for precise type mapping
|
|
68
|
-
- Schema export - Auto-generates JSON schemas for client code generation
|
|
69
|
-
- Multi-language clients - Generate type-safe clients in TypeScript, C#, Go, Java
|
|
70
|
-
- Cross-plugin events - Type-safe communication between plugins (no `any` types)
|
|
71
|
-
|
|
46
|
+
- `tests/`: Mocha + ts-node test suite
|
|
47
|
+
- `lib/`: Compiled JavaScript output (generated by `tsc`)
|
|
48
|
+
- `templates/`: Scaffolding for new plugins (`plugin.ts`, `pluginClient.ts`, `events.ts`, `logger.ts`)
|
|
49
|
+
- `Dockerfile`, `entrypoint.sh`, `entrypoint.js`: Container build/runtime assets
|
|
50
|
+
- `typedoc.json`, `docs.json`, `typedoc-theme/`: API docs generation configuration/theme
|
|
51
|
+
|
|
52
|
+
### What's New in v9
|
|
53
|
+
|
|
54
|
+
v9 introduces breaking changes focused on type safety, developer experience, and cross-language support:
|
|
55
|
+
|
|
56
|
+
**Type Safety Improvements:**
|
|
57
|
+
- `createEventSchemas()` - No more `as const` required, automatic type inference
|
|
58
|
+
- Type branding - Compile-time validation that event types match categories
|
|
59
|
+
- Duplicate name detection - Warns about confusing duplicate event names
|
|
60
|
+
|
|
61
|
+
**Simplified Configuration:**
|
|
62
|
+
- `createConfigSchema()` - Single function replaces class pattern
|
|
63
|
+
- Plugin metadata - Define once, auto-generates PLUGIN_CLIENT and bsb-plugin.json
|
|
64
|
+
- Centralized schemas - All generated JSON in lib/schemas/ with JSON $ref references
|
|
65
|
+
|
|
66
|
+
**Cross-Language Support:**
|
|
67
|
+
- Type helpers - int32, int64, uuid, datetime for precise type mapping
|
|
68
|
+
- Schema export - Auto-generates JSON schemas for client code generation
|
|
69
|
+
- Multi-language clients - Generate type-safe clients in TypeScript, C#, Go, Java
|
|
70
|
+
- Cross-plugin events - Type-safe communication between plugins (no `any` types)
|
|
71
|
+
|
|
72
72
|
See [Plugin Development Guide](https://github.com/BetterCorp/better-service-base/blob/master/nodejs/PLUGIN_DEVELOPMENT.md) for migration details and examples.
|
|
73
|
-
|
|
73
|
+
|
|
74
74
|
### Runtime Architecture
|
|
75
75
|
The `ServiceBase` class is the primary entry point. It coordinates the framework subsystems and plugin lifecycle.
|
|
76
76
|
|
|
@@ -88,7 +88,7 @@ Boot flow (high level):
|
|
|
88
88
|
- Disposes services, events, observable, and config; exits the process
|
|
89
89
|
|
|
90
90
|
Timekeeping metrics are recorded for each step and logged as timers. A heartbeat counter runs hourly.
|
|
91
|
-
|
|
91
|
+
|
|
92
92
|
### Subsystems
|
|
93
93
|
- `SBConfig` (configuration)
|
|
94
94
|
- Defaults to `config-default` plugin; can be replaced via environment variables
|
|
@@ -102,64 +102,64 @@ Timekeeping metrics are recorded for each step and logged as timers. A heartbeat
|
|
|
102
102
|
- Offers APIs for broadcast, fire-and-forget, request/response, and streaming
|
|
103
103
|
- `SBServices` (services)
|
|
104
104
|
- Loads service plugins from config, re-maps declared `init/run` before/after dependencies, and initializes/runs them in order
|
|
105
|
-
|
|
106
|
-
### Plugin Resolution & Layout
|
|
107
|
-
`SBPlugins` looks for plugins in the following order (container usage prefers the first external option):
|
|
108
|
-
- Local project (dev): `src/plugins/<type>-<name>/index.ts`
|
|
109
|
-
- Local build: `lib/plugins/<type>-<name>/index.js`
|
|
110
|
-
- External plugin
|
|
105
|
+
|
|
106
|
+
### Plugin Resolution & Layout
|
|
107
|
+
`SBPlugins` looks for plugins in the following order (container usage prefers the first external option):
|
|
108
|
+
- Local project (dev): `src/plugins/<type>-<name>/index.ts`
|
|
109
|
+
- Local build: `lib/plugins/<type>-<name>/index.js`
|
|
110
|
+
- External plugin directories (`BSB_PLUGIN_DIRS`, comma-separated) [preferred in container]: `<dir>/<npmPackage>/<major>/<minor>/<micro>/lib/plugins/<type>-<name>/index.js`
|
|
111
111
|
- Node modules: `node_modules/<npmPackage>/lib/plugins/<type>-<name>/index.js`
|
|
112
|
-
|
|
112
|
+
|
|
113
113
|
Each plugin folder must export at least a `Plugin` class. Optionally export a `Config` class that extends `BSBPluginConfig` to provide validation and structured config.
|
|
114
114
|
|
|
115
115
|
Built-in plugin types include: `config-*`, `observable-*`, `events-*`, `service-*`.
|
|
116
|
-
|
|
117
|
-
### Development vs Production
|
|
118
|
-
- Container runtime (production): The container runs `lib/cli.js` (bin: `bsb`) and is the supported production path.
|
|
119
|
-
- Runs `new ServiceBase(false, true, CWD)` (legacy signature -> optimized for production) inside the container entrypoint.
|
|
120
|
-
- Development runner: `src/dev.ts`
|
|
121
|
-
- Runs `new ServiceBase(true, false, CWD)` with file watching
|
|
122
|
-
- Creates `.bsbdevwatch` on first run; supports include/exclude patterns
|
|
123
|
-
- Interactive controls:
|
|
124
|
-
- `Ctrl+R` or typing `rs` to restart
|
|
125
|
-
- `Ctrl+C`/`Ctrl+D` to dispose and exit
|
|
126
|
-
|
|
127
|
-
### NPM Scripts
|
|
128
|
-
- `npm run dev`: Start development runner with hot-reload
|
|
129
|
-
- `npm start`: Run production CLI (`lib/cli.js` or `bsb`)
|
|
130
|
-
- `npm run tsc`: Clean and compile TypeScript to `lib/`
|
|
131
|
-
- `npm run build`: Clean -> tsc -> tests -> generate docs -> export schemas -> generate plugin metadata
|
|
132
|
-
- `npm run build-release`: Compile using `tsconfig-release.json`
|
|
133
|
-
- `npm run lint`: ESLint over `src/`
|
|
134
|
-
- `npm test`: Mocha + NYC coverage in TS mode
|
|
135
|
-
- `npm run testDev`: Run tests without coverage (faster for development)
|
|
136
|
-
- `npm run generate-docs`: Generate TypeDoc JSON to `docs.json`
|
|
137
|
-
- API Reference: Hosted at `https://types.bsbcode.dev/nodejs/`
|
|
138
|
-
- `npm run export-schemas`: Export event schemas to `lib/schemas/{plugin-name}.json`
|
|
139
|
-
- `npm run generate-plugin-json`: Generate plugin metadata in `lib/schemas/`
|
|
140
|
-
|
|
141
|
-
### Docker
|
|
142
|
-
Multi-stage build produces a minimal runtime image:
|
|
143
|
-
- `ENV BSB_LIVE=true`, `ENV BSB_CONTAINER=true`, `ENV
|
|
144
|
-
- Volumes: `/mnt/plugins` (external plugins), `/mnt/temp`
|
|
145
|
-
- Entrypoint runs `node lib/cli.js` as an unprivileged `node` user
|
|
146
|
-
- Optional plugin install/update at startup:
|
|
147
|
-
- `BSB_PLUGINS="@scope/plugin-a:1.2.3,@scope/plugin-b"` -> installs/updates listed packages
|
|
148
|
-
- `BSB_PLUGIN_UPDATE=yes` -> runs `npm update`
|
|
149
|
-
|
|
150
|
-
Example run (with mounted plugins directory):
|
|
151
|
-
```bash
|
|
152
|
-
docker run --rm \
|
|
153
|
-
-e BSB_PLUGINS="@bettercorp/your-plugin" \
|
|
154
|
-
-v $(pwd)/plugins:/mnt/plugins \
|
|
155
|
-
betterweb/service-base:9
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
Recommended plugin directory layout (when using `
|
|
159
|
-
```
|
|
160
|
-
/mnt/plugins/
|
|
161
|
-
@org/plugin-a/
|
|
162
|
-
1/2/3/
|
|
116
|
+
|
|
117
|
+
### Development vs Production
|
|
118
|
+
- Container runtime (production): The container runs `lib/cli.js` (bin: `bsb`) and is the supported production path.
|
|
119
|
+
- Runs `new ServiceBase(false, true, CWD)` (legacy signature -> optimized for production) inside the container entrypoint.
|
|
120
|
+
- Development runner: `src/dev.ts`
|
|
121
|
+
- Runs `new ServiceBase(true, false, CWD)` with file watching
|
|
122
|
+
- Creates `.bsbdevwatch` on first run; supports include/exclude patterns
|
|
123
|
+
- Interactive controls:
|
|
124
|
+
- `Ctrl+R` or typing `rs` to restart
|
|
125
|
+
- `Ctrl+C`/`Ctrl+D` to dispose and exit
|
|
126
|
+
|
|
127
|
+
### NPM Scripts
|
|
128
|
+
- `npm run dev`: Start development runner with hot-reload
|
|
129
|
+
- `npm start`: Run production CLI (`lib/cli.js` or `bsb`)
|
|
130
|
+
- `npm run tsc`: Clean and compile TypeScript to `lib/`
|
|
131
|
+
- `npm run build`: Clean -> tsc -> tests -> generate docs -> export schemas -> generate plugin metadata
|
|
132
|
+
- `npm run build-release`: Compile using `tsconfig-release.json`
|
|
133
|
+
- `npm run lint`: ESLint over `src/`
|
|
134
|
+
- `npm test`: Mocha + NYC coverage in TS mode
|
|
135
|
+
- `npm run testDev`: Run tests without coverage (faster for development)
|
|
136
|
+
- `npm run generate-docs`: Generate TypeDoc JSON to `docs.json`
|
|
137
|
+
- API Reference: Hosted at `https://types.bsbcode.dev/nodejs/`
|
|
138
|
+
- `npm run export-schemas`: Export event schemas to `lib/schemas/{plugin-name}.json`
|
|
139
|
+
- `npm run generate-plugin-json`: Generate plugin metadata in `lib/schemas/`
|
|
140
|
+
|
|
141
|
+
### Docker
|
|
142
|
+
Multi-stage build produces a minimal runtime image:
|
|
143
|
+
- `ENV BSB_LIVE=true`, `ENV BSB_CONTAINER=true`, `ENV BSB_PLUGIN_DIRS=/mnt/plugins`
|
|
144
|
+
- Volumes: `/mnt/plugins` (external plugins), `/mnt/temp`
|
|
145
|
+
- Entrypoint runs `node lib/cli.js` as an unprivileged `node` user
|
|
146
|
+
- Optional plugin install/update at startup:
|
|
147
|
+
- `BSB_PLUGINS="@scope/plugin-a:1.2.3,@scope/plugin-b"` -> installs/updates listed packages
|
|
148
|
+
- `BSB_PLUGIN_UPDATE=yes` -> runs `npm update`
|
|
149
|
+
|
|
150
|
+
Example run (with mounted plugins directory):
|
|
151
|
+
```bash
|
|
152
|
+
docker run --rm \
|
|
153
|
+
-e BSB_PLUGINS="@bettercorp/your-plugin" \
|
|
154
|
+
-v $(pwd)/plugins:/mnt/plugins \
|
|
155
|
+
betterweb/service-base:9
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Recommended plugin directory layout (when using `BSB_PLUGIN_DIRS`):
|
|
159
|
+
```
|
|
160
|
+
/mnt/plugins/
|
|
161
|
+
@org/plugin-a/
|
|
162
|
+
1/2/3/
|
|
163
163
|
package.json
|
|
164
164
|
lib/plugins/service-plugin-a/index.js
|
|
165
165
|
lib/plugins/observable-xyz/index.js
|
|
@@ -167,60 +167,62 @@ Recommended plugin directory layout (when using `BSB_PLUGIN_DIR`):
|
|
|
167
167
|
2/4/1/
|
|
168
168
|
package.json
|
|
169
169
|
lib/plugins/events-abc/index.js
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
Notes
|
|
173
|
-
- In container deployments, prefer placing prebuilt plugins under `
|
|
174
|
-
- `BSB_PLUGINS` is available for dynamic `npm install` at startup, but mounting a curated plugin repository via `
|
|
175
|
-
|
|
176
|
-
### Environment Variables
|
|
177
|
-
- `APP_DIR`: Override working directory (mainly used in local development/testing)
|
|
178
|
-
- `
|
|
179
|
-
- `
|
|
180
|
-
- `
|
|
181
|
-
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Notes
|
|
173
|
+
- In container deployments, prefer placing prebuilt plugins under `BSB_PLUGIN_DIRS` as above. This avoids network installs on boot and ensures deterministic versions via immutable versioned folders.
|
|
174
|
+
- `BSB_PLUGINS` is available for dynamic `npm install` at startup, but mounting a curated plugin repository via `BSB_PLUGIN_DIRS` is recommended for production.
|
|
175
|
+
|
|
176
|
+
### Environment Variables
|
|
177
|
+
- `APP_DIR`: Override working directory (mainly used in local development/testing)
|
|
178
|
+
- `BSB_DEBUG`: Enable debug logging in production mode (`true|1|yes|y`). Produces `production-debug` mode.
|
|
179
|
+
- `BSB_PLUGIN_DIRS`: Comma-separated list of external plugin directories (searched in order; first is install target)
|
|
180
|
+
- `BSB_PLUGIN_DIR`: Single external plugin directory (legacy, still supported). Accepts comma-separated paths.
|
|
181
|
+
- `BSB_PLUGINS`: Comma-separated list of npm packages to install at container start (entrypoint.js)
|
|
182
|
+
- `BSB_PLUGIN_UPDATE`: `yes|y|true` to run `npm update` at container start
|
|
183
|
+
- Config plugin override (advanced):
|
|
184
|
+
- `BSB_CONFIG_PLUGIN`: Name of config plugin (must start with `config-`)
|
|
185
|
+
- `BSB_CONFIG_PLUGIN_PACKAGE`: npm package name hosting the config plugin
|
|
186
|
+
|
|
187
|
+
### Documentation
|
|
188
|
+
|
|
189
|
+
#### Plugin Development (v9)
|
|
188
190
|
- [Plugin Development Guide](https://github.com/BetterCorp/better-service-base/blob/master/nodejs/PLUGIN_DEVELOPMENT.md) - Complete guide for creating BSB plugins
|
|
189
191
|
- [Type System Guide](https://github.com/BetterCorp/better-service-base/blob/master/nodejs/TYPE_SYSTEM.md) - Cross-language type system reference
|
|
190
|
-
|
|
191
|
-
#### API Documentation
|
|
192
|
-
- API docs are generated with TypeDoc (`typedoc.json`).
|
|
193
|
-
- `npm run generate-docs` -> emits `docs.json`
|
|
194
|
-
- API docs are served at `https://types.bsbcode.dev/nodejs/`
|
|
195
|
-
|
|
196
|
-
### Testing
|
|
197
|
-
- Tests: Mocha + ts-node with NYC coverage
|
|
198
|
-
- `npm test` -> CI-style JSON + lcov reports (`coverage/`)
|
|
199
|
-
- `npm run testDev` -> dev-friendly TS execution
|
|
200
|
-
|
|
201
|
-
### Creating Plugins
|
|
202
|
-
|
|
192
|
+
|
|
193
|
+
#### API Documentation
|
|
194
|
+
- API docs are generated with TypeDoc (`typedoc.json`).
|
|
195
|
+
- `npm run generate-docs` -> emits `docs.json`
|
|
196
|
+
- API docs are served at `https://types.bsbcode.dev/nodejs/`
|
|
197
|
+
|
|
198
|
+
### Testing
|
|
199
|
+
- Tests: Mocha + ts-node with NYC coverage
|
|
200
|
+
- `npm test` -> CI-style JSON + lcov reports (`coverage/`)
|
|
201
|
+
- `npm run testDev` -> dev-friendly TS execution
|
|
202
|
+
|
|
203
|
+
### Creating Plugins
|
|
204
|
+
|
|
203
205
|
**For v9 plugin development, see the [Plugin Development Guide](https://github.com/BetterCorp/better-service-base/blob/master/nodejs/PLUGIN_DEVELOPMENT.md) for complete examples and best practices.**
|
|
204
|
-
|
|
205
|
-
Quick reference:
|
|
206
|
-
- Use `createEventSchemas()` to define typed events with compile-time validation
|
|
207
|
-
- Use `createConfigSchema()` to define plugin configuration with metadata
|
|
208
|
-
- Use cross-language type helpers (`uuid`, `int32`, `datetime`, etc.) for better code generation
|
|
209
|
-
- Plugin metadata auto-generates `PLUGIN_CLIENT` and schema files during build
|
|
210
|
-
|
|
211
|
-
At minimum, export a `Plugin` class in `lib/plugins/<type>-<name>/index.js` (or `src/plugins/.../index.ts` in dev). For configurable plugins, export a `Config` created with `createConfigSchema()`. Publish your plugin as an npm package or ship its prebuilt folder structure under `
|
|
212
|
-
|
|
213
|
-
### Quick Start (Container)
|
|
214
|
-
```bash
|
|
215
|
-
# Provide prebuilt plugins under ./plugins, matching the recommended layout
|
|
216
|
-
docker run --rm \
|
|
217
|
-
-v $(pwd)/plugins:/mnt/plugins:ro \
|
|
218
|
-
-e BSB_PLUGIN_DIR=/mnt/plugins \
|
|
219
|
-
betterweb/service-base:9
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
Local development (for contributors only):
|
|
223
|
-
```bash
|
|
224
|
-
npm install
|
|
225
|
-
npm run dev
|
|
226
|
-
```
|
|
206
|
+
|
|
207
|
+
Quick reference:
|
|
208
|
+
- Use `createEventSchemas()` to define typed events with compile-time validation
|
|
209
|
+
- Use `createConfigSchema()` to define plugin configuration with metadata
|
|
210
|
+
- Use cross-language type helpers (`uuid`, `int32`, `datetime`, etc.) for better code generation
|
|
211
|
+
- Plugin metadata auto-generates `PLUGIN_CLIENT` and schema files during build
|
|
212
|
+
|
|
213
|
+
At minimum, export a `Plugin` class in `lib/plugins/<type>-<name>/index.js` (or `src/plugins/.../index.ts` in dev). For configurable plugins, export a `Config` created with `createConfigSchema()`. Publish your plugin as an npm package or ship its prebuilt folder structure under `BSB_PLUGIN_DIRS`.
|
|
214
|
+
|
|
215
|
+
### Quick Start (Container)
|
|
216
|
+
```bash
|
|
217
|
+
# Provide prebuilt plugins under ./plugins, matching the recommended layout
|
|
218
|
+
docker run --rm \
|
|
219
|
+
-v $(pwd)/plugins:/mnt/plugins:ro \
|
|
220
|
+
-e BSB_PLUGIN_DIR=/mnt/plugins \
|
|
221
|
+
betterweb/service-base:9
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Local development (for contributors only):
|
|
225
|
+
```bash
|
|
226
|
+
npm install
|
|
227
|
+
npm run dev
|
|
228
|
+
```
|
package/lib/cli.js
CHANGED
|
@@ -38,10 +38,12 @@ const MODULE_DIR = getModuleDir(import.meta.url);
|
|
|
38
38
|
/**
|
|
39
39
|
* Run the BSB service (default behavior).
|
|
40
40
|
*/
|
|
41
|
+
const TRUTHY_VALUES = new Set(["true", "1", "yes", "y"]);
|
|
41
42
|
const runApp = async () => {
|
|
42
43
|
const CWD = process.env.APP_DIR || process.cwd();
|
|
44
|
+
const debugEnabled = TRUTHY_VALUES.has(String(process.env.BSB_DEBUG || "").trim().toLowerCase());
|
|
43
45
|
const SB = new ServiceBase({
|
|
44
|
-
debug:
|
|
46
|
+
debug: debugEnabled,
|
|
45
47
|
live: true,
|
|
46
48
|
cwd: CWD,
|
|
47
49
|
runtimeMode: "prod",
|
|
@@ -84,39 +86,41 @@ const syncSchemas = async () => {
|
|
|
84
86
|
* Show CLI usage.
|
|
85
87
|
*/
|
|
86
88
|
const showUsage = () => {
|
|
87
|
-
console.log(`
|
|
88
|
-
BSB CLI - Better Service Base Framework
|
|
89
|
-
|
|
90
|
-
Usage:
|
|
91
|
-
bsb Run the BSB service (default)
|
|
92
|
-
bsb client <command> Client type and schema management
|
|
93
|
-
|
|
94
|
-
Client Commands (Local Schema Operations):
|
|
95
|
-
bsb client sync Export schemas and generate types (recommended)
|
|
96
|
-
bsb client export Export event schemas from all plugins to JSON
|
|
97
|
-
bsb client generate Generate TypeScript client types from schemas
|
|
98
|
-
|
|
99
|
-
Client Commands (Registry Operations):
|
|
100
|
-
bsb client list List all plugins from registry
|
|
101
|
-
bsb client search <query> Search for plugins by name or tag
|
|
102
|
-
bsb client info <org/name> Get plugin details from registry
|
|
103
|
-
bsb client schema <org/name> Get plugin event schema from registry
|
|
104
|
-
bsb client install <org/name> Download schema and generate types
|
|
105
|
-
bsb client publish Publish current plugin to registry
|
|
106
|
-
bsb client token generate Generate API token for registry
|
|
107
|
-
|
|
108
|
-
Examples:
|
|
109
|
-
bsb # Start the service
|
|
110
|
-
bsb client sync # Export schemas and generate client types
|
|
111
|
-
bsb client list # List all plugins from registry
|
|
112
|
-
bsb client search todo # Search for plugins matching "todo"
|
|
113
|
-
bsb client publish # Publish current plugin to registry
|
|
114
|
-
|
|
115
|
-
Environment Variables:
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
89
|
+
console.log(`
|
|
90
|
+
BSB CLI - Better Service Base Framework
|
|
91
|
+
|
|
92
|
+
Usage:
|
|
93
|
+
bsb Run the BSB service (default)
|
|
94
|
+
bsb client <command> Client type and schema management
|
|
95
|
+
|
|
96
|
+
Client Commands (Local Schema Operations):
|
|
97
|
+
bsb client sync Export schemas and generate types (recommended)
|
|
98
|
+
bsb client export Export event schemas from all plugins to JSON
|
|
99
|
+
bsb client generate Generate TypeScript client types from schemas
|
|
100
|
+
|
|
101
|
+
Client Commands (Registry Operations):
|
|
102
|
+
bsb client list List all plugins from registry
|
|
103
|
+
bsb client search <query> Search for plugins by name or tag
|
|
104
|
+
bsb client info <org/name> Get plugin details from registry
|
|
105
|
+
bsb client schema <org/name> Get plugin event schema from registry
|
|
106
|
+
bsb client install <org/name> Download schema and generate types
|
|
107
|
+
bsb client publish Publish current plugin to registry
|
|
108
|
+
bsb client token generate Generate API token for registry
|
|
109
|
+
|
|
110
|
+
Examples:
|
|
111
|
+
bsb # Start the service
|
|
112
|
+
bsb client sync # Export schemas and generate client types
|
|
113
|
+
bsb client list # List all plugins from registry
|
|
114
|
+
bsb client search todo # Search for plugins matching "todo"
|
|
115
|
+
bsb client publish # Publish current plugin to registry
|
|
116
|
+
|
|
117
|
+
Environment Variables:
|
|
118
|
+
BSB_DEBUG Enable debug logging in production (true|1|yes|y)
|
|
119
|
+
BSB_PLUGIN_DIRS Comma-separated external plugin directories
|
|
120
|
+
BSB_REGISTRY_URL Registry URL (default: http://localhost:3100)
|
|
121
|
+
BSB_REGISTRY_TOKEN API token for authentication
|
|
122
|
+
|
|
123
|
+
For more information, visit: https://bsbcode.dev
|
|
120
124
|
`);
|
|
121
125
|
};
|
|
122
126
|
/**
|
package/lib/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACrE;;GAEG;AAEH,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAChC,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,GAAG,KAAK,IAAI,EAAE;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACjD,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC;QACzB,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
|
File without changes
|