@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 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.
@@ -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;
@@ -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 };
@@ -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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sdflc/backend-helpers",
3
- "version": "1.0.124",
3
+ "version": "1.0.125",
4
4
  "description": "Set of helper functions and classes to simplify building backend apps within @sdflc ecosystem",
5
5
  "type": "commonjs",
6
6
  "exports": {