110 lines
5.9 KiB
Markdown
110 lines
5.9 KiB
Markdown
# Design — @suaveplan/booking
|
|
|
|
## Architecture overview
|
|
|
|
The booking engine is a pipeline composed of six pluggable stages, each owned by an isolated feature module:
|
|
|
|
```text
|
|
Availability → Conflict detection → Pricing → Rules → State machine → Events
|
|
```
|
|
|
|
Every stage is registry-driven (`registerDetector`, `registerAvailabilityStrategy`) so callers can extend behaviour without forking. The pipeline orchestrator is `BookingEngine`, which holds in-memory `Map<id, Bookable | Booking | BookingHold>` registries plus an in-package `Hooks<BookingHookMap>` instance and an `EventBus`.
|
|
|
|
## File layout
|
|
|
|
```text
|
|
src/
|
|
index.ts — explicit named root barrel
|
|
error-codes/
|
|
error-codes.ts | error-codes.test.ts | error-codes.md | index.ts
|
|
hooks/
|
|
hooks.ts | hooks.test.ts | hooks.md | hooks.types.ts | index.ts
|
|
utils/
|
|
utils.ts | utils.test.ts | utils.md | index.ts
|
|
constants/
|
|
constants.ts | constants.md | index.ts
|
|
types/
|
|
bookable.types.ts (+ .md)
|
|
booking.types.ts (+ .md)
|
|
booking-hooks.ts (+ .md)
|
|
capacity.types.ts (+ .md)
|
|
config.types.ts (+ .md)
|
|
events.types.ts (+ .md)
|
|
layout.types.ts (+ .md)
|
|
pricing.types.ts (+ .md)
|
|
rules.types.ts (+ .md)
|
|
temporal.types.ts (+ .md)
|
|
temporal/
|
|
windows/(windows.ts + test + md + index)
|
|
recurrence/(…)
|
|
slots/(…)
|
|
conflict/
|
|
detector/(detector.ts + .types.ts + test + md + index)
|
|
exact-match/(…) | range-overlap/(…) | slot-capacity/(…) | provider-overlap/(…)
|
|
pricing/
|
|
calculator/(calculator.ts + .types.ts + test + md + index)
|
|
seasonal/(…) | dynamic/(…)
|
|
rules/
|
|
evaluator/(evaluator.ts + .types.ts + test + md + index)
|
|
conditions/(…)
|
|
availability/
|
|
resolver/(resolver.ts + .types.ts + test + md + index)
|
|
strategies/(strategies.ts + .types.ts + test + md + index)
|
|
domains/
|
|
shared.ts | shared.test.ts | shared.md | index.ts
|
|
seats/(seats.ts + .types.ts + test + md + index)
|
|
accommodation/(…) | appointments/(…) | resources/(…)
|
|
activities/(…) | transport/(…)
|
|
schemas/
|
|
booking.schema.ts | booking.schema.test.ts | booking.schema.md | index.ts
|
|
config.schema.ts | config.schema.test.ts | config.schema.md
|
|
core/
|
|
engine/(engine.ts + .types.ts + test + md + index)
|
|
state-machine/(state-machine.ts + test + md + index)
|
|
event-bus/(event-bus.ts + test + md + index)
|
|
conformance.spec-conformance.test.ts — barrel + subpath conformance
|
|
tests/
|
|
setup/polyfills.ts
|
|
```
|
|
|
|
## Key decisions
|
|
|
|
### 1. In-package `Hooks<TMap>` (vs. depending on `@suaveplan/events/hooks`)
|
|
|
|
Genesis `@suaveplan/events` does not yet expose `/hooks` or `/hooks.types`. Rather than block this migration on a separate `events-hooks` change, the upstream Hooks impl is re-implemented in-package under `src/hooks/` with the same public surface. The `BookingHookMap` is defined locally so `Hooks<BookingHookMap>` works without external types. When events ships its hooks subpath, the in-package impl can be removed in a follow-up; the contract preserved here matches the upstream surface exactly so consumers do not need to change.
|
|
|
|
### 2. Typed errors over plain `throw new Error`
|
|
|
|
Every boundary that previously raised a plain `Error` now raises a `BookingError` extending `SuaveplanError<BookingErrorCode>`. Codes are stable namespaced strings (`"BOOKING.ENGINE_NOT_CONFIGURED"`). Optional discriminants — `bookingId`, `holdId`, `mode`, `strategy` — are attached without polluting the base `context` map; consumers can read them on the typed instance after a narrow.
|
|
|
|
The `Hooks` sync-path `console.warn` (upstream behaviour when a handler returns a Promise) is upgraded to a `BookingError({ code: BOOKING.HOOK_RETURNED_PROMISE_IN_SYNC })`. Universal-tier libraries should not log to stdout; the typed error lets callers decide how to handle the bug.
|
|
|
|
### 3. Module-level mutable registries preserved
|
|
|
|
Upstream uses module-level `Map<>` registries for conflict detectors and availability strategies. The migration preserves this for parity (downstream callers depend on the global mutation). A future change can pivot to scoped registries; that is an out-of-scope behaviour change.
|
|
|
|
### 4. Determinism is upstream's responsibility
|
|
|
|
Upstream uses `Date.now()` and `Math.random()` inside `generateId` for in-memory id generation. The migration preserves both. Tests assert structural properties (prefix, uniqueness across N calls) rather than exact strings; a future change can thread an injectable `IdGenerator` from `@suaveplan/types` once consumers need deterministic ids.
|
|
|
|
### 5. Subpath exports
|
|
|
|
Each feature module gets a subpath in `package.json` `exports` so consumers like `@suaveplan/r3f-booking` can import only `@suaveplan/booking/temporal/windows/windows` and skip the engine + schemas + rule evaluator. Tree-shaking is verified at build time (preserveModules + sideEffects:false).
|
|
|
|
## Public surface inventory
|
|
|
|
- Engine + types (`createBookingEngine`, `BookingEngine`, `BookingEngineInterface`, `AvailabilityQuery`, `AvailabilityResult`, `ConflictResult`, `PriceCalculationRequest`)
|
|
- State machine (`StateMachine`, `createStateMachine`, `TransitionRequest`, `TransitionResult`)
|
|
- Event bus (`EventBus`, `createEventBus`)
|
|
- Hooks (`Hooks`, `HookMap`, `HookContext`, `HookHandler`, `HookHandlerOptions`, `HookResult`, `RegisteredHook`, `Hookable`)
|
|
- Temporal (windows: 9 fns; recurrence: 3 fns; slots: 4 fns)
|
|
- Conflict (detector: 4 fns + types; 4 built-ins)
|
|
- Pricing (calculator: 5 fns + types; seasonal: 4 fns; dynamic: 4 fns + types)
|
|
- Rules (evaluator: 2 fns; conditions: 8 factories)
|
|
- Availability (resolver: 4 fns + types; strategies: 3 built-ins + `SlotAvailability` type)
|
|
- Domains (base + 6 presets + 6 meta types)
|
|
- Schemas (6 entity + 1 config + 5 validate/safe-validate helpers)
|
|
- Errors (`BOOKING_CODES`, `BookingError`, `BookingErrorCode`, `BookingErrorOptions`)
|
|
- Utils (5 helpers) + Constants (15 entries)
|
|
- All upstream type names preserved verbatim (50+)
|