@sdflc/backend-helpers 1.0.124 → 1.0.125
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/README.md +55 -0
- package/build/BaseCore.d.ts +40 -0
- package/build/BaseCore.js +58 -0
- package/build/esm/BaseCore.d.ts +40 -0
- package/build/esm/BaseCore.js +58 -0
- package/build/esm/interfaces/BaseCoreActionsInterface.d.ts +26 -0
- package/build/interfaces/BaseCoreActionsInterface.d.ts +26 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -661,6 +661,61 @@ return this.runAction({
|
|
|
661
661
|
|
|
662
662
|
---
|
|
663
663
|
|
|
664
|
+
#### Action-scoped request store
|
|
665
|
+
|
|
666
|
+
When you need to share data between a `before*` hook and its corresponding `after*` hook — for example, fetching a record once before an update and reusing it for audit logging afterward — `BaseCore` provides a typed key-value store scoped to a single action invocation. A fresh store is created for every `runAction` call, so there is no bleed between `list()`, `create()`, etc., even on the same core instance.
|
|
667
|
+
|
|
668
|
+
Use the three protected helpers from any `before*`, `after*`, `validate`, or `action` handler:
|
|
669
|
+
|
|
670
|
+
| Method | Signature | Description |
|
|
671
|
+
| ------------------ | ---------------------------------- | ------------------------------------------------------------------------- |
|
|
672
|
+
| `storeSet<T>` | `(opt, key, value) → T` | Stores a value; returns it as a pass-through |
|
|
673
|
+
| `storeGet<T>` | `(opt, key) → T \| undefined` | Retrieves a typed value; `undefined` when absent |
|
|
674
|
+
| `storeGetOrSet<T>` | `(opt, key, factory) → Promise<T>` | Returns stored value or calls `factory()`, stores, and returns the result |
|
|
675
|
+
|
|
676
|
+
Define keys as constants to catch typos at compile time:
|
|
677
|
+
|
|
678
|
+
```typescript
|
|
679
|
+
// src/core/ProductCore.ts
|
|
680
|
+
const STORE = {
|
|
681
|
+
ORIGINAL_RECORD: 'originalRecord',
|
|
682
|
+
PARENT_CATEGORY: 'parentCategory',
|
|
683
|
+
} as const;
|
|
684
|
+
|
|
685
|
+
class ProductCore extends AppCore {
|
|
686
|
+
async beforeUpdate(params: any, opt: BaseCoreActionsInterface): Promise<any> {
|
|
687
|
+
// Fetch the current record once; storeGetOrSet avoids a second DB hit if
|
|
688
|
+
// another hook already loaded it.
|
|
689
|
+
const current = await this.storeGetOrSet(opt, STORE.ORIGINAL_RECORD, () =>
|
|
690
|
+
this.getGateway().get(opt.args?.where?.id),
|
|
691
|
+
);
|
|
692
|
+
|
|
693
|
+
this.logger.debug(`Updating product, original slug was '${current?.slug}'`);
|
|
694
|
+
return this.processItemOnIn(params, opt);
|
|
695
|
+
}
|
|
696
|
+
|
|
697
|
+
async afterUpdate(items: any[], opt: BaseCoreActionsInterface): Promise<any> {
|
|
698
|
+
const original = this.storeGet<{ slug: string }>(opt, STORE.ORIGINAL_RECORD);
|
|
699
|
+
|
|
700
|
+
if (original?.slug && items[0]?.slug !== original.slug) {
|
|
701
|
+
this.logger.log(`Product slug changed from '${original.slug}' to '${items[0]?.slug}'; updating references`);
|
|
702
|
+
// trigger side effects — redirect rules, search index update, etc.
|
|
703
|
+
}
|
|
704
|
+
|
|
705
|
+
return Promise.all(items.map((item) => this.processItemOnOut(item, opt)));
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
**Notes:**
|
|
711
|
+
|
|
712
|
+
- Prefer `storeGetOrSet` for anything fetched from the database — it guarantees at most one DB call per action invocation regardless of how many hooks reference the same key.
|
|
713
|
+
- The store is also available inside the `validate` function and the inline `action` handler passed to `runAction()` via the `opt` argument.
|
|
714
|
+
- The store is not shared between a parent call and a nested same-request call — each `runAction` invocation gets its own independent `Map`.
|
|
715
|
+
- `storeGet` uses `Map.has()` internally, so storing `null` or `false` is treated as a hit, not a miss.
|
|
716
|
+
|
|
717
|
+
---
|
|
718
|
+
|
|
664
719
|
### BaseGateway
|
|
665
720
|
|
|
666
721
|
The base class for all database-backed data access. One gateway per table.
|
package/build/BaseCore.d.ts
CHANGED
|
@@ -659,5 +659,45 @@ declare class BaseCore {
|
|
|
659
659
|
* @param args.gateway Gateway instance to query for the current max orderNo
|
|
660
660
|
*/
|
|
661
661
|
setOrderNo(args: any): Promise<void>;
|
|
662
|
+
/**
|
|
663
|
+
* Stores a typed value in the action-scoped request store.
|
|
664
|
+
*
|
|
665
|
+
* Prefer this over opt.requestStore.set() directly — the return value
|
|
666
|
+
* lets callers write `const v = this.storeSet(opt, key, expensiveValue)`
|
|
667
|
+
* without a separate declaration.
|
|
668
|
+
*
|
|
669
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
670
|
+
* @param key Unique string key — define keys as constants to avoid typos
|
|
671
|
+
* @param value Any value to store; retrieved with storeGet<T>()
|
|
672
|
+
* @returns The stored value (pass-through for convenience)
|
|
673
|
+
*/
|
|
674
|
+
protected storeSet<T>(opt: BaseCoreActionsInterface, key: string, value: T): T;
|
|
675
|
+
/**
|
|
676
|
+
* Retrieves a typed value from the action-scoped request store.
|
|
677
|
+
*
|
|
678
|
+
* Returns undefined when the key is absent. Use opt.requestStore.has(key)
|
|
679
|
+
* beforehand if you need to distinguish a stored undefined from a missing key.
|
|
680
|
+
*
|
|
681
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
682
|
+
* @param key The key used in a prior storeSet() call
|
|
683
|
+
*/
|
|
684
|
+
protected storeGet<T>(opt: BaseCoreActionsInterface, key: string): T | undefined;
|
|
685
|
+
/**
|
|
686
|
+
* Returns the stored value when present; otherwise calls factory(), stores
|
|
687
|
+
* the result, and returns it.
|
|
688
|
+
*
|
|
689
|
+
* Use for values that are expensive to compute (e.g. a DB fetch) and may
|
|
690
|
+
* be needed by multiple hooks in the same action invocation.
|
|
691
|
+
*
|
|
692
|
+
* Example — fetch a parent record once, reuse in both beforeUpdate and afterUpdate:
|
|
693
|
+
* const parent = await this.storeGetOrSet(opt, 'parentRecord', () =>
|
|
694
|
+
* this.getGateway('parentGw').get(params.parentId)
|
|
695
|
+
* );
|
|
696
|
+
*
|
|
697
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
698
|
+
* @param key Cache key — same string used by storeSet() / storeGet()
|
|
699
|
+
* @param factory Called on cache miss; may be async or sync
|
|
700
|
+
*/
|
|
701
|
+
protected storeGetOrSet<T>(opt: BaseCoreActionsInterface, key: string, factory: () => T | Promise<T>): Promise<T>;
|
|
662
702
|
}
|
|
663
703
|
export { BaseCore };
|
package/build/BaseCore.js
CHANGED
|
@@ -594,6 +594,7 @@ class BaseCore {
|
|
|
594
594
|
setStep,
|
|
595
595
|
sameRequest,
|
|
596
596
|
hasTransaction,
|
|
597
|
+
requestStore: new Map(),
|
|
597
598
|
};
|
|
598
599
|
try {
|
|
599
600
|
// ── Step 1: Rate limiting ──────────────────────────────────────────────
|
|
@@ -1486,5 +1487,62 @@ class BaseCore {
|
|
|
1486
1487
|
}
|
|
1487
1488
|
}
|
|
1488
1489
|
}
|
|
1490
|
+
// ─── Action-scoped request store helpers ──────────────────────────────────
|
|
1491
|
+
// These helpers provide typed access to the per-action requestStore carried
|
|
1492
|
+
// in BaseCoreActionsInterface.opt. Use them in any before*, after*, validate,
|
|
1493
|
+
// or action handler to share data across hooks within a single action
|
|
1494
|
+
// invocation without adding instance properties to the subclass.
|
|
1495
|
+
/**
|
|
1496
|
+
* Stores a typed value in the action-scoped request store.
|
|
1497
|
+
*
|
|
1498
|
+
* Prefer this over opt.requestStore.set() directly — the return value
|
|
1499
|
+
* lets callers write `const v = this.storeSet(opt, key, expensiveValue)`
|
|
1500
|
+
* without a separate declaration.
|
|
1501
|
+
*
|
|
1502
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
1503
|
+
* @param key Unique string key — define keys as constants to avoid typos
|
|
1504
|
+
* @param value Any value to store; retrieved with storeGet<T>()
|
|
1505
|
+
* @returns The stored value (pass-through for convenience)
|
|
1506
|
+
*/
|
|
1507
|
+
storeSet(opt, key, value) {
|
|
1508
|
+
opt.requestStore.set(key, value);
|
|
1509
|
+
return value;
|
|
1510
|
+
}
|
|
1511
|
+
/**
|
|
1512
|
+
* Retrieves a typed value from the action-scoped request store.
|
|
1513
|
+
*
|
|
1514
|
+
* Returns undefined when the key is absent. Use opt.requestStore.has(key)
|
|
1515
|
+
* beforehand if you need to distinguish a stored undefined from a missing key.
|
|
1516
|
+
*
|
|
1517
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
1518
|
+
* @param key The key used in a prior storeSet() call
|
|
1519
|
+
*/
|
|
1520
|
+
storeGet(opt, key) {
|
|
1521
|
+
return opt.requestStore.get(key);
|
|
1522
|
+
}
|
|
1523
|
+
/**
|
|
1524
|
+
* Returns the stored value when present; otherwise calls factory(), stores
|
|
1525
|
+
* the result, and returns it.
|
|
1526
|
+
*
|
|
1527
|
+
* Use for values that are expensive to compute (e.g. a DB fetch) and may
|
|
1528
|
+
* be needed by multiple hooks in the same action invocation.
|
|
1529
|
+
*
|
|
1530
|
+
* Example — fetch a parent record once, reuse in both beforeUpdate and afterUpdate:
|
|
1531
|
+
* const parent = await this.storeGetOrSet(opt, 'parentRecord', () =>
|
|
1532
|
+
* this.getGateway('parentGw').get(params.parentId)
|
|
1533
|
+
* );
|
|
1534
|
+
*
|
|
1535
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
1536
|
+
* @param key Cache key — same string used by storeSet() / storeGet()
|
|
1537
|
+
* @param factory Called on cache miss; may be async or sync
|
|
1538
|
+
*/
|
|
1539
|
+
async storeGetOrSet(opt, key, factory) {
|
|
1540
|
+
if (opt.requestStore.has(key)) {
|
|
1541
|
+
return opt.requestStore.get(key);
|
|
1542
|
+
}
|
|
1543
|
+
const value = await factory();
|
|
1544
|
+
opt.requestStore.set(key, value);
|
|
1545
|
+
return value;
|
|
1546
|
+
}
|
|
1489
1547
|
}
|
|
1490
1548
|
exports.BaseCore = BaseCore;
|
package/build/esm/BaseCore.d.ts
CHANGED
|
@@ -659,5 +659,45 @@ declare class BaseCore {
|
|
|
659
659
|
* @param args.gateway Gateway instance to query for the current max orderNo
|
|
660
660
|
*/
|
|
661
661
|
setOrderNo(args: any): Promise<void>;
|
|
662
|
+
/**
|
|
663
|
+
* Stores a typed value in the action-scoped request store.
|
|
664
|
+
*
|
|
665
|
+
* Prefer this over opt.requestStore.set() directly — the return value
|
|
666
|
+
* lets callers write `const v = this.storeSet(opt, key, expensiveValue)`
|
|
667
|
+
* without a separate declaration.
|
|
668
|
+
*
|
|
669
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
670
|
+
* @param key Unique string key — define keys as constants to avoid typos
|
|
671
|
+
* @param value Any value to store; retrieved with storeGet<T>()
|
|
672
|
+
* @returns The stored value (pass-through for convenience)
|
|
673
|
+
*/
|
|
674
|
+
protected storeSet<T>(opt: BaseCoreActionsInterface, key: string, value: T): T;
|
|
675
|
+
/**
|
|
676
|
+
* Retrieves a typed value from the action-scoped request store.
|
|
677
|
+
*
|
|
678
|
+
* Returns undefined when the key is absent. Use opt.requestStore.has(key)
|
|
679
|
+
* beforehand if you need to distinguish a stored undefined from a missing key.
|
|
680
|
+
*
|
|
681
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
682
|
+
* @param key The key used in a prior storeSet() call
|
|
683
|
+
*/
|
|
684
|
+
protected storeGet<T>(opt: BaseCoreActionsInterface, key: string): T | undefined;
|
|
685
|
+
/**
|
|
686
|
+
* Returns the stored value when present; otherwise calls factory(), stores
|
|
687
|
+
* the result, and returns it.
|
|
688
|
+
*
|
|
689
|
+
* Use for values that are expensive to compute (e.g. a DB fetch) and may
|
|
690
|
+
* be needed by multiple hooks in the same action invocation.
|
|
691
|
+
*
|
|
692
|
+
* Example — fetch a parent record once, reuse in both beforeUpdate and afterUpdate:
|
|
693
|
+
* const parent = await this.storeGetOrSet(opt, 'parentRecord', () =>
|
|
694
|
+
* this.getGateway('parentGw').get(params.parentId)
|
|
695
|
+
* );
|
|
696
|
+
*
|
|
697
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
698
|
+
* @param key Cache key — same string used by storeSet() / storeGet()
|
|
699
|
+
* @param factory Called on cache miss; may be async or sync
|
|
700
|
+
*/
|
|
701
|
+
protected storeGetOrSet<T>(opt: BaseCoreActionsInterface, key: string, factory: () => T | Promise<T>): Promise<T>;
|
|
662
702
|
}
|
|
663
703
|
export { BaseCore };
|
package/build/esm/BaseCore.js
CHANGED
|
@@ -588,6 +588,7 @@ class BaseCore {
|
|
|
588
588
|
setStep,
|
|
589
589
|
sameRequest,
|
|
590
590
|
hasTransaction,
|
|
591
|
+
requestStore: new Map(),
|
|
591
592
|
};
|
|
592
593
|
try {
|
|
593
594
|
// ── Step 1: Rate limiting ──────────────────────────────────────────────
|
|
@@ -1480,5 +1481,62 @@ class BaseCore {
|
|
|
1480
1481
|
}
|
|
1481
1482
|
}
|
|
1482
1483
|
}
|
|
1484
|
+
// ─── Action-scoped request store helpers ──────────────────────────────────
|
|
1485
|
+
// These helpers provide typed access to the per-action requestStore carried
|
|
1486
|
+
// in BaseCoreActionsInterface.opt. Use them in any before*, after*, validate,
|
|
1487
|
+
// or action handler to share data across hooks within a single action
|
|
1488
|
+
// invocation without adding instance properties to the subclass.
|
|
1489
|
+
/**
|
|
1490
|
+
* Stores a typed value in the action-scoped request store.
|
|
1491
|
+
*
|
|
1492
|
+
* Prefer this over opt.requestStore.set() directly — the return value
|
|
1493
|
+
* lets callers write `const v = this.storeSet(opt, key, expensiveValue)`
|
|
1494
|
+
* without a separate declaration.
|
|
1495
|
+
*
|
|
1496
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
1497
|
+
* @param key Unique string key — define keys as constants to avoid typos
|
|
1498
|
+
* @param value Any value to store; retrieved with storeGet<T>()
|
|
1499
|
+
* @returns The stored value (pass-through for convenience)
|
|
1500
|
+
*/
|
|
1501
|
+
storeSet(opt, key, value) {
|
|
1502
|
+
opt.requestStore.set(key, value);
|
|
1503
|
+
return value;
|
|
1504
|
+
}
|
|
1505
|
+
/**
|
|
1506
|
+
* Retrieves a typed value from the action-scoped request store.
|
|
1507
|
+
*
|
|
1508
|
+
* Returns undefined when the key is absent. Use opt.requestStore.has(key)
|
|
1509
|
+
* beforehand if you need to distinguish a stored undefined from a missing key.
|
|
1510
|
+
*
|
|
1511
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
1512
|
+
* @param key The key used in a prior storeSet() call
|
|
1513
|
+
*/
|
|
1514
|
+
storeGet(opt, key) {
|
|
1515
|
+
return opt.requestStore.get(key);
|
|
1516
|
+
}
|
|
1517
|
+
/**
|
|
1518
|
+
* Returns the stored value when present; otherwise calls factory(), stores
|
|
1519
|
+
* the result, and returns it.
|
|
1520
|
+
*
|
|
1521
|
+
* Use for values that are expensive to compute (e.g. a DB fetch) and may
|
|
1522
|
+
* be needed by multiple hooks in the same action invocation.
|
|
1523
|
+
*
|
|
1524
|
+
* Example — fetch a parent record once, reuse in both beforeUpdate and afterUpdate:
|
|
1525
|
+
* const parent = await this.storeGetOrSet(opt, 'parentRecord', () =>
|
|
1526
|
+
* this.getGateway('parentGw').get(params.parentId)
|
|
1527
|
+
* );
|
|
1528
|
+
*
|
|
1529
|
+
* @param opt The BaseCoreActionsInterface opt object from any hook
|
|
1530
|
+
* @param key Cache key — same string used by storeSet() / storeGet()
|
|
1531
|
+
* @param factory Called on cache miss; may be async or sync
|
|
1532
|
+
*/
|
|
1533
|
+
async storeGetOrSet(opt, key, factory) {
|
|
1534
|
+
if (opt.requestStore.has(key)) {
|
|
1535
|
+
return opt.requestStore.get(key);
|
|
1536
|
+
}
|
|
1537
|
+
const value = await factory();
|
|
1538
|
+
opt.requestStore.set(key, value);
|
|
1539
|
+
return value;
|
|
1540
|
+
}
|
|
1483
1541
|
}
|
|
1484
1542
|
export { BaseCore };
|
|
@@ -35,4 +35,30 @@ export interface BaseCoreActionsInterface {
|
|
|
35
35
|
* Object with incoming request params
|
|
36
36
|
*/
|
|
37
37
|
args?: any;
|
|
38
|
+
/**
|
|
39
|
+
* Ephemeral key-value store scoped to a single action invocation.
|
|
40
|
+
* Initialized by runAction() before any hook is called and shared
|
|
41
|
+
* across all before*, after*, validate, and action calls within
|
|
42
|
+
* that invocation.
|
|
43
|
+
*
|
|
44
|
+
* Use this instead of instance properties on subclasses to pass
|
|
45
|
+
* data between beforeXxx and afterXxx without polluting core state.
|
|
46
|
+
*
|
|
47
|
+
* Prefer the typed helpers on BaseCore — storeSet(), storeGet(), and
|
|
48
|
+
* storeGetOrSet() — over calling opt.requestStore directly, to keep
|
|
49
|
+
* call sites readable and to get compile-time type inference.
|
|
50
|
+
*
|
|
51
|
+
* Example:
|
|
52
|
+
* async beforeCreate(params, opt) {
|
|
53
|
+
* const existing = await this.getGateway().get(params.parentId);
|
|
54
|
+
* this.storeSet(opt, 'parentRecord', existing);
|
|
55
|
+
* return params;
|
|
56
|
+
* }
|
|
57
|
+
*
|
|
58
|
+
* async afterCreate(items, opt) {
|
|
59
|
+
* const parent = this.storeGet<ParentRecord>(opt, 'parentRecord');
|
|
60
|
+
* // use parent here without re-fetching
|
|
61
|
+
* }
|
|
62
|
+
*/
|
|
63
|
+
requestStore: Map<string, unknown>;
|
|
38
64
|
}
|
|
@@ -35,4 +35,30 @@ export interface BaseCoreActionsInterface {
|
|
|
35
35
|
* Object with incoming request params
|
|
36
36
|
*/
|
|
37
37
|
args?: any;
|
|
38
|
+
/**
|
|
39
|
+
* Ephemeral key-value store scoped to a single action invocation.
|
|
40
|
+
* Initialized by runAction() before any hook is called and shared
|
|
41
|
+
* across all before*, after*, validate, and action calls within
|
|
42
|
+
* that invocation.
|
|
43
|
+
*
|
|
44
|
+
* Use this instead of instance properties on subclasses to pass
|
|
45
|
+
* data between beforeXxx and afterXxx without polluting core state.
|
|
46
|
+
*
|
|
47
|
+
* Prefer the typed helpers on BaseCore — storeSet(), storeGet(), and
|
|
48
|
+
* storeGetOrSet() — over calling opt.requestStore directly, to keep
|
|
49
|
+
* call sites readable and to get compile-time type inference.
|
|
50
|
+
*
|
|
51
|
+
* Example:
|
|
52
|
+
* async beforeCreate(params, opt) {
|
|
53
|
+
* const existing = await this.getGateway().get(params.parentId);
|
|
54
|
+
* this.storeSet(opt, 'parentRecord', existing);
|
|
55
|
+
* return params;
|
|
56
|
+
* }
|
|
57
|
+
*
|
|
58
|
+
* async afterCreate(items, opt) {
|
|
59
|
+
* const parent = this.storeGet<ParentRecord>(opt, 'parentRecord');
|
|
60
|
+
* // use parent here without re-fetching
|
|
61
|
+
* }
|
|
62
|
+
*/
|
|
63
|
+
requestStore: Map<string, unknown>;
|
|
38
64
|
}
|