@sdflc/backend-helpers 1.0.123 → 1.0.124
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 +208 -45
- package/build/BaseGateway.d.ts +39 -0
- package/build/BaseGateway.js +80 -0
- package/build/esm/BaseGateway.d.ts +39 -0
- package/build/esm/BaseGateway.js +81 -1
- package/build/esm/interfaces/BaseGatewayPropsInterface.d.ts +17 -0
- package/build/interfaces/BaseGatewayPropsInterface.d.ts +17 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -720,24 +720,174 @@ export { NoteGw };
|
|
|
720
720
|
|
|
721
721
|
#### Gateway config flags
|
|
722
722
|
|
|
723
|
-
| Flag
|
|
724
|
-
|
|
|
725
|
-
| `table`
|
|
726
|
-
| `idField`
|
|
727
|
-
| `
|
|
728
|
-
| `
|
|
729
|
-
| `
|
|
730
|
-
| `
|
|
731
|
-
| `
|
|
732
|
-
| `
|
|
733
|
-
| `
|
|
734
|
-
| `
|
|
735
|
-
| `
|
|
736
|
-
| `
|
|
737
|
-
| `
|
|
738
|
-
| `
|
|
739
|
-
| `
|
|
740
|
-
| `
|
|
723
|
+
| Flag | Type | Description |
|
|
724
|
+
| ---------------------- | --------------------- | ------------------------------------------------------------------------------------------------ |
|
|
725
|
+
| `table` | `string` | Database table name |
|
|
726
|
+
| `idField` | `string` | Primary key for SELECT/loader — table-qualify for joined queries (default: `id`) |
|
|
727
|
+
| `idFieldAs` | `string` | Alias for the id column when it differs from the lookup key |
|
|
728
|
+
| `idFieldUpdateRemove` | `string` | Primary key for UPDATE/DELETE WHERE — must be unqualified |
|
|
729
|
+
| `setFields` | `string \| string[]` | Conflict target field(s) for the `set()` upsert operation |
|
|
730
|
+
| `mergeFields` | `string[]` | Explicit field list for the ON CONFLICT MERGE clause |
|
|
731
|
+
| `hasStatus` | `boolean` | Status filtering and REMOVED guard |
|
|
732
|
+
| `hasCreatedAt` | `boolean` | Auto-set `created_at` on insert |
|
|
733
|
+
| `hasUpdatedAt` | `boolean` | Auto-set `updated_at` on update |
|
|
734
|
+
| `hasRemovedAt` | `boolean` | Soft-delete via `removed_at` timestamp |
|
|
735
|
+
| `hasRemovedAtStr` | `boolean` | Also writes a formatted string timestamp to `removed_at_str` |
|
|
736
|
+
| `hasCreatedBy` | `boolean` | Auto-set `created_by` from `context.userId` on insert |
|
|
737
|
+
| `hasUpdatedBy` | `boolean` | Auto-set `updated_by` from `context.userId` on update |
|
|
738
|
+
| `hasRemovedBy` | `boolean` | Auto-set `removed_by` from `context.userId` on soft-delete |
|
|
739
|
+
| `hasSpace` | `boolean` | Scopes reads/writes to `context.spaceId` |
|
|
740
|
+
| `hasUserId` | `boolean` | Sets `userId` from context on create |
|
|
741
|
+
| `hasVersion` | `boolean` | Optimistic locking via version field |
|
|
742
|
+
| `hasLang` | `boolean` | Language-scoped records |
|
|
743
|
+
| `localizationForField` | `string` | Field combined with `lang` to build a composite localisation id |
|
|
744
|
+
| `hardRemove` | `boolean` | Hard DELETE instead of soft-delete |
|
|
745
|
+
| `noCache` | `boolean` | Bypass DataLoader cache |
|
|
746
|
+
| `returnFields` | `string[]` | Columns in RETURNING clause (default: `['*']`) |
|
|
747
|
+
| `defaultSorting` | `SortItemInterface[]` | Default ORDER BY when none provided |
|
|
748
|
+
| `filterByUserField` | `string` | Auto-scope list queries to `context.userId` |
|
|
749
|
+
| `fieldForKeyword` | `string` | Column to apply keyword ILIKE/LIKE search against |
|
|
750
|
+
| `selectFields` | `string[]` | Columns selected when `useCache: false` (default: `['*']`) |
|
|
751
|
+
| `activeStatuses` | `number[]` | Status values considered active for list filtering |
|
|
752
|
+
| `insertChunkSize` | `number` | Records per INSERT batch — prevents DB parameter limit errors (default: `2500`) |
|
|
753
|
+
| `listFilters` | `GatewayFilterRule[]` | Declarative WHERE rules for `list()` — see [Declarative filter rules](#declarative-filter-rules) |
|
|
754
|
+
| `updateFilters` | `GatewayFilterRule[]` | Declarative WHERE rules for `update()` |
|
|
755
|
+
| `removeFilters` | `GatewayFilterRule[]` | Declarative WHERE rules for `remove()` |
|
|
756
|
+
| `countFilters` | `GatewayFilterRule[]` | Declarative WHERE rules for `count()` — falls back to `listFilters` when not set |
|
|
757
|
+
|
|
758
|
+
#### Filter hooks
|
|
759
|
+
|
|
760
|
+
| Hook | Signature | Purpose |
|
|
761
|
+
| ---------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
|
|
762
|
+
| `onListFilter` | `(query, filterParams) => Promise<void>` | Custom WHERE clauses for `list()` |
|
|
763
|
+
| `onUpdateFilter` | `(query, whereParams) => Promise<number>` | Custom WHERE clauses for `update()` — return incremented count |
|
|
764
|
+
| `onRemoveFilter` | `(query, whereParams) => Promise<number>` | Custom WHERE clauses for `remove()` — return incremented count |
|
|
765
|
+
| `onCountFilter` | `(query, filterParams) => void` | Custom WHERE clauses for `count()` |
|
|
766
|
+
| `buildListQuery` | `(args: BuildListQueryArgsInterface) => Promise<any>` | Override to add JOINs and computed columns to list queries |
|
|
767
|
+
|
|
768
|
+
Always call `super.onListFilter()` / `super.onUpdateFilter()` / `super.onRemoveFilter()` at the top of any override so base-class scoping (soft-delete, space, user) runs first.
|
|
769
|
+
|
|
770
|
+
---
|
|
771
|
+
|
|
772
|
+
#### Declarative filter rules
|
|
773
|
+
|
|
774
|
+
For the common case of simple equality or array `IN` filters, declarative rules eliminate the need to override `onListFilter`, `onUpdateFilter`, `onRemoveFilter`, or `onCountFilter` at all. Rules are passed in the constructor props and applied automatically after the base-class scoping logic.
|
|
775
|
+
|
|
776
|
+
```typescript
|
|
777
|
+
class PartyGuestGw extends BaseGateway {
|
|
778
|
+
private static readonly DOMAIN_FILTER_RULES = [
|
|
779
|
+
{ field: 'partyId', column: 'Party_Guest.Party_ID', type: 'array' as const },
|
|
780
|
+
{ field: 'rsvpStatus', column: 'Party_Guest.Rsvp_Status', type: 'array' as const },
|
|
781
|
+
{ field: 'wasInvited', column: 'Party_Guest.Invited_At', type: 'nullableBool' as const },
|
|
782
|
+
{ field: 'rsvpAt', column: 'Party_Guest.Rsvp_At', type: 'nullableDateRange' as const },
|
|
783
|
+
{ field: 'isStarred', column: 'Party_Guest.Is_Starred', type: 'bool' as const },
|
|
784
|
+
{
|
|
785
|
+
field: 'search',
|
|
786
|
+
column: '',
|
|
787
|
+
type: 'search' as const,
|
|
788
|
+
columns: ['Person.First_Name', 'Person.Last_Name', 'Person.Email'],
|
|
789
|
+
},
|
|
790
|
+
];
|
|
791
|
+
|
|
792
|
+
constructor(props: BaseGatewayPropsInterface) {
|
|
793
|
+
super({
|
|
794
|
+
...props,
|
|
795
|
+
table: TABLES.PARTY_GUEST,
|
|
796
|
+
listFilters: PartyGuestGw.DOMAIN_FILTER_RULES,
|
|
797
|
+
updateFilters: PartyGuestGw.DOMAIN_FILTER_RULES,
|
|
798
|
+
removeFilters: PartyGuestGw.DOMAIN_FILTER_RULES,
|
|
799
|
+
// countFilters omitted — BaseGateway falls back to listFilters automatically
|
|
800
|
+
});
|
|
801
|
+
}
|
|
802
|
+
}
|
|
803
|
+
```
|
|
804
|
+
|
|
805
|
+
**Best practice:** define the rules once as a `private static readonly` constant and reference it from all four filter props. This ensures `list`, `update`, `remove`, and `count` always stay in sync without duplicating the field/column/type data.
|
|
806
|
+
|
|
807
|
+
#### Filter rule types
|
|
808
|
+
|
|
809
|
+
Each `GatewayFilterRule` has a `type` that determines the WHERE clause strategy:
|
|
810
|
+
|
|
811
|
+
| Type | Behaviour |
|
|
812
|
+
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
813
|
+
| `array` | `whereIn(column, values)` for arrays; `where(column, value)` for scalars. Skipped when value is `null`/`undefined`/`''`. |
|
|
814
|
+
| `eq` | `where(column, value)`. Strict single-value equality — never expands to `whereIn`. Skipped when value is `null`/`undefined`. |
|
|
815
|
+
| `bool` | `where(column, true\|false)`. Fires only on strict `true` or `false`; `null`/`undefined` leaves the column unconstrained. |
|
|
816
|
+
| `nullableBool` | `true` → `whereNotNull(column)` / `false` → `whereNull(column)` / `null`/`undefined` → skipped. Use when a nullable datetime encodes presence (e.g. `invitedAt IS [NOT] NULL`). |
|
|
817
|
+
| `dateRange` | Reads `filter[field + 'From']` and `filter[field + 'To']`. Applies `>=` and/or `<=` bounds independently. The `field` value is the base name (e.g. `'rsvpAt'`); actual keys are `rsvpAtFrom` / `rsvpAtTo`. |
|
|
818
|
+
| `nullableDateRange` | Extends `dateRange` with a `filter[field + 'Null']` boolean: `true` → `whereNull` (from/to skipped); `false` → `whereNotNull` (from/to still applied); `null`/`undefined` → null-ness unconstrained. |
|
|
819
|
+
| `search` | `LIKE`/`ILIKE` across one or more columns with OR semantics. Reads `filter[field]` (string). Requires the `columns` array on the rule. The operator is resolved per-database (`ilike` on PostgreSQL, `like` on MSSQL/MySQL). |
|
|
820
|
+
|
|
821
|
+
Rules with unsupported types on `updateFilters`/`removeFilters` (`search`, `dateRange`, `nullableDateRange`) are silently skipped with a warning — update and remove filters must be precise identifiers.
|
|
822
|
+
|
|
823
|
+
#### count()
|
|
824
|
+
|
|
825
|
+
Returns the count of non-removed rows matching a filter. Applies the same soft-delete, space, and user scoping as `list()`, then runs `onCountFilter()` and the declarative `countFilters` rules (falling back to `listFilters` when `countFilters` is not set).
|
|
826
|
+
|
|
827
|
+
```typescript
|
|
828
|
+
// In a core method:
|
|
829
|
+
const total = await this.gateway.count({ partyId: args.partyId, rsvpStatus: [1, 2] });
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
Gateways that already declare `listFilters` get `count()` for free with no additional configuration. Set `countFilters` explicitly only when count needs different scoping than list.
|
|
833
|
+
|
|
834
|
+
To add custom WHERE logic beyond what declarative rules express, override `onCountFilter()`:
|
|
835
|
+
|
|
836
|
+
```typescript
|
|
837
|
+
protected onCountFilter(query: any, filterParams: any): void {
|
|
838
|
+
if (filterParams?.accountId) {
|
|
839
|
+
query.where(`${TABLES.PARTY}.${FIELDS.ACCOUNT_ID}`, filterParams.accountId);
|
|
840
|
+
}
|
|
841
|
+
}
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
---
|
|
845
|
+
|
|
846
|
+
#### Join-variant gateways
|
|
847
|
+
|
|
848
|
+
For read operations that need columns from related tables alongside the primary table, create additional read-only gateway variants that add JOINs via `buildListQuery`. The base gateway remains the sole source of truth for mutations.
|
|
849
|
+
|
|
850
|
+
```typescript
|
|
851
|
+
// PartyGuestGw — base gateway: all mutations, count(), plain reads
|
|
852
|
+
// PartyGuestWithMainPersonGw — read-only: joins Person for name/email/phone
|
|
853
|
+
// PartyGuestWithFullPersonGw — read-only: joins Person + avatar + extra fields
|
|
854
|
+
|
|
855
|
+
class PartyGuestWithMainPersonGw extends PartyGuestGw {
|
|
856
|
+
constructor(props: BaseGatewayPropsInterface) {
|
|
857
|
+
super({
|
|
858
|
+
...props,
|
|
859
|
+
// Each variant must have a unique keyPrefix to prevent DataLoader
|
|
860
|
+
// cache collisions between plain and joined result sets.
|
|
861
|
+
keyPrefix: 'party-guest-with-person',
|
|
862
|
+
selectFields: [
|
|
863
|
+
`${TABLES.PARTY_GUEST}.*`,
|
|
864
|
+
`${TABLES.PERSON}.${FIELDS.FIRST_NAME}`,
|
|
865
|
+
`${TABLES.PERSON}.${FIELDS.EMAIL}`,
|
|
866
|
+
`${TABLES.PERSON}.${FIELDS.PHONE}`,
|
|
867
|
+
],
|
|
868
|
+
});
|
|
869
|
+
}
|
|
870
|
+
|
|
871
|
+
// Join logic lives in buildListQuery, not in list() itself.
|
|
872
|
+
// This ensures the framework's cache/direct-query branching is respected —
|
|
873
|
+
// when useCache is true, only ids are selected here and the DataLoader
|
|
874
|
+
// hydrates records; the join only fires on the useCache: false path.
|
|
875
|
+
protected async buildListQuery(args: BuildListQueryArgsInterface): Promise<any> {
|
|
876
|
+
const query = await super.buildListQuery(args);
|
|
877
|
+
|
|
878
|
+
query.leftJoin(TABLES.PERSON, `${TABLES.PERSON}.${FIELDS.ID}`, `${TABLES.PARTY_GUEST}.${FIELDS.PERSON_ID}`);
|
|
879
|
+
|
|
880
|
+
return query;
|
|
881
|
+
}
|
|
882
|
+
}
|
|
883
|
+
```
|
|
884
|
+
|
|
885
|
+
**Rules for join-variant gateways:**
|
|
886
|
+
|
|
887
|
+
- **Mutations always go through the base gateway** — join variants are strictly read-only
|
|
888
|
+
- **Each variant needs a unique `keyPrefix`** — prevents cross-contamination between plain and joined result sets in the DataLoader cache
|
|
889
|
+
- **Join logic belongs in `buildListQuery`**, not in `onListFilter` or `list()` — this respects the framework's `useCache` branching
|
|
890
|
+
- **`idField` must be table-qualified** in the base gateway (`Party_Guest.ID`) to prevent ambiguity in joined queries
|
|
741
891
|
|
|
742
892
|
---
|
|
743
893
|
|
|
@@ -1593,13 +1743,22 @@ const isCorrect = await checkPassword(plaintextPassword, storedHash);
|
|
|
1593
1743
|
```typescript
|
|
1594
1744
|
import { FIELDS, HEADERS, ORDER_BYS, ID_TYPES } from '@sdflc/backend-helpers';
|
|
1595
1745
|
|
|
1746
|
+
// Primary key and standard columns
|
|
1596
1747
|
FIELDS.ID; // 'id'
|
|
1597
1748
|
FIELDS.STATUS; // 'status'
|
|
1598
|
-
FIELDS.CREATED_AT; // 'created_at'
|
|
1599
1749
|
FIELDS.SPACE_ID; // 'space_id'
|
|
1600
1750
|
FIELDS.USER_ID; // 'user_id'
|
|
1601
1751
|
FIELDS.LANG; // 'lang'
|
|
1602
1752
|
FIELDS.ORDER_NO; // 'order_no'
|
|
1753
|
+
FIELDS.VERSION; // 'version'
|
|
1754
|
+
|
|
1755
|
+
// Audit / timestamp columns
|
|
1756
|
+
FIELDS.CREATED_AT; // 'created_at'
|
|
1757
|
+
FIELDS.UPDATED_AT; // 'updated_at'
|
|
1758
|
+
FIELDS.REMOVED_AT; // 'removed_at'
|
|
1759
|
+
FIELDS.CREATED_BY; // 'created_by'
|
|
1760
|
+
FIELDS.UPDATED_BY; // 'updated_by'
|
|
1761
|
+
FIELDS.REMOVED_BY; // 'removed_by' ← soft-delete sentinel used by BaseGateway.count()
|
|
1603
1762
|
|
|
1604
1763
|
HEADERS.AUTHORIZATION; // 'authorization'
|
|
1605
1764
|
HEADERS.SPACE_ID; // 'x-space-id'
|
|
@@ -1620,29 +1779,33 @@ ORDER_BYS.DESC; // 'desc'
|
|
|
1620
1779
|
|
|
1621
1780
|
## Interfaces reference
|
|
1622
1781
|
|
|
1623
|
-
| Interface | Description
|
|
1624
|
-
| ----------------------------------------- |
|
|
1625
|
-
| `ApiContext` | Request context object shape
|
|
1626
|
-
| `ApiContextInterface` | Arguments for `createApiContext()`
|
|
1627
|
-
| `BaseCorePropsInterface` | Constructor props for `BaseCore` subclasses
|
|
1628
|
-
| `BaseCoreRateLimitOnActionInterface` | Per-action rate-limit rule map used in `BaseCorePropsInterface`
|
|
1629
|
-
| `BaseGatewayPropsInterface` | Constructor props for `BaseGateway` subclasses
|
|
1630
|
-
| `BaseExternalApiGatewayPropsInterface` | Constructor props for `BaseExternalApiGateway`
|
|
1631
|
-
| `BaseRestApiCrudControllerPropsInterface` | Constructor props for `BaseRestApiCrudController`
|
|
1632
|
-
| `BuildDefaultResolvers` | Arguments for `buildDefaultResolvers()`
|
|
1633
|
-
| `
|
|
1634
|
-
| `
|
|
1635
|
-
| `
|
|
1636
|
-
| `
|
|
1637
|
-
| `
|
|
1638
|
-
| `
|
|
1639
|
-
| `
|
|
1640
|
-
| `
|
|
1641
|
-
| `
|
|
1642
|
-
| `
|
|
1643
|
-
| `
|
|
1644
|
-
| `
|
|
1645
|
-
| `
|
|
1646
|
-
| `
|
|
1647
|
-
| `
|
|
1648
|
-
| `
|
|
1782
|
+
| Interface | Description |
|
|
1783
|
+
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1784
|
+
| `ApiContext` | Request context object shape |
|
|
1785
|
+
| `ApiContextInterface` | Arguments for `createApiContext()` |
|
|
1786
|
+
| `BaseCorePropsInterface` | Constructor props for `BaseCore` subclasses |
|
|
1787
|
+
| `BaseCoreRateLimitOnActionInterface` | Per-action rate-limit rule map used in `BaseCorePropsInterface` |
|
|
1788
|
+
| `BaseGatewayPropsInterface` | Constructor props for `BaseGateway` subclasses |
|
|
1789
|
+
| `BaseExternalApiGatewayPropsInterface` | Constructor props for `BaseExternalApiGateway` |
|
|
1790
|
+
| `BaseRestApiCrudControllerPropsInterface` | Constructor props for `BaseRestApiCrudController` |
|
|
1791
|
+
| `BuildDefaultResolvers` | Arguments for `buildDefaultResolvers()` |
|
|
1792
|
+
| `BuildListQueryArgsInterface` | Arguments passed to `buildListQuery()` overrides: `{ filter, params, fieldsToUse, useCache }` |
|
|
1793
|
+
| `BuildConfigOptions` | Options for `buildConfig()` |
|
|
1794
|
+
| `DatabaseOptions` | Options for `Database` constructor |
|
|
1795
|
+
| `DatabaseReadInterface` | Arguments for `Database.read()` |
|
|
1796
|
+
| `CacheInterface` | Config for `DataCache` (without request context) |
|
|
1797
|
+
| `DataCachePropsInterface` | Full props for `DataCache` including request context |
|
|
1798
|
+
| `LoaderInterface` | Interface for custom loaders (`load`, `loadMany`, `clear`, `prime`) |
|
|
1799
|
+
| `GatewayFilterRule` | Single declarative filter rule: `{ field, column, type, columns? }` — used by `listFilters` / `updateFilters` / `removeFilters` / `countFilters` |
|
|
1800
|
+
| `GatewayFilterType` | Union of filter strategy names: `'array' \| 'eq' \| 'bool' \| 'nullableBool' \| 'dateRange' \| 'nullableDateRange' \| 'search'` |
|
|
1801
|
+
| `SortItemInterface` | Single sort descriptor: `{ name: string, order: 'asc' \| 'desc' }` |
|
|
1802
|
+
| `RateLimitRule` | Rate-limit rule shape: `{ limit, windowSec, action? }` |
|
|
1803
|
+
| `RateLimiterInterface` | Structural interface for custom rate-limiter implementations |
|
|
1804
|
+
| `IpRateLimiter` | Built-in Redis-backed rate limiter; constructed automatically from `redisClient` |
|
|
1805
|
+
| `CoreActionInterface` | Arguments for `BaseCore.runAction()` including `tryAuth` and `rateLimit` |
|
|
1806
|
+
| `CreateUserTokenArgs` | Options for `createUserToken()` |
|
|
1807
|
+
| `VerifyUserTokenArgs` | Options for `verifyUserToken()` |
|
|
1808
|
+
| `UserTokenParams` | JWT payload structure |
|
|
1809
|
+
| `DownloadFileArgs` | Arguments for `downloadFile()` |
|
|
1810
|
+
| `DbFieldAddDefaultInterface` | Options for `dbFieldAddDefaults()` |
|
|
1811
|
+
| `ListArgsInterface` | Standard list operation arguments |
|
package/build/BaseGateway.d.ts
CHANGED
|
@@ -372,6 +372,20 @@ declare class BaseGateway {
|
|
|
372
372
|
* - `removeFilters` — applies declarative GatewayFilterRule array (new)
|
|
373
373
|
*/
|
|
374
374
|
onRemoveFilter(query: any, filterParams: any): Promise<number>;
|
|
375
|
+
/**
|
|
376
|
+
* Hook called by count() to apply custom WHERE conditions to the count query.
|
|
377
|
+
*
|
|
378
|
+
* Parallel to onListFilter() — override in subclasses that need filter logic
|
|
379
|
+
* beyond what the declarative countFilters rules can express (OR conditions,
|
|
380
|
+
* subqueries, cross-table joins, etc.).
|
|
381
|
+
*
|
|
382
|
+
* The base implementation is a no-op. Call super.onCountFilter() when
|
|
383
|
+
* overriding so future base-class logic is not silently skipped.
|
|
384
|
+
*
|
|
385
|
+
* @param query Knex query builder for the count query
|
|
386
|
+
* @param filterParams The raw filter object passed to count()
|
|
387
|
+
*/
|
|
388
|
+
protected onCountFilter(query: any, filterParams: any): void;
|
|
375
389
|
/**
|
|
376
390
|
* Transforms a params object before it is inserted into the database.
|
|
377
391
|
* Called once per object inside the `create()` loop, after the ID is generated.
|
|
@@ -671,5 +685,30 @@ declare class BaseGateway {
|
|
|
671
685
|
* `transformOnOut()`.
|
|
672
686
|
*/
|
|
673
687
|
remove(where: any): Promise<any[]>;
|
|
688
|
+
/**
|
|
689
|
+
* Returns the count of non-removed rows matching the given filter.
|
|
690
|
+
*
|
|
691
|
+
* Applies the same soft-delete, space, and user scoping that list() uses,
|
|
692
|
+
* ensuring count() and list() always agree on which rows are "visible" for
|
|
693
|
+
* an identical filter. Uses COUNT(*) — no column data is read, so this is
|
|
694
|
+
* as cheap as possible on both PostgreSQL and MS Azure SQL.
|
|
695
|
+
*
|
|
696
|
+
* Filter application order (mirrors list()):
|
|
697
|
+
* 1. Soft-delete guard — WHERE Removed_By IS NULL (when hasRemovedBy)
|
|
698
|
+
* WHERE Removed_At IS NULL (when hasRemovedAt and
|
|
699
|
+
* not hasRemovedBy — rare, but handled for safety)
|
|
700
|
+
* 2. Space scoping — WHERE Space_ID = context.spaceId (if hasSpace)
|
|
701
|
+
* 3. User scoping — WHERE {filterByUserField} = context.userId (if set)
|
|
702
|
+
* 4. onCountFilter() hook — subclass custom logic
|
|
703
|
+
* 5. Declarative rules — countFilters when set, otherwise listFilters
|
|
704
|
+
*
|
|
705
|
+
* Subclasses that need count with different scoping than list have two options:
|
|
706
|
+
* A) Set explicit countFilters in the constructor props.
|
|
707
|
+
* B) Override onCountFilter() for logic that declarative rules cannot express.
|
|
708
|
+
*
|
|
709
|
+
* @param filterParams Filter object (same shape as passed to list())
|
|
710
|
+
* @returns Row count as a number; 0 when nothing matches or on error
|
|
711
|
+
*/
|
|
712
|
+
count(filterParams: any): Promise<number>;
|
|
674
713
|
}
|
|
675
714
|
export { BaseGateway };
|
package/build/BaseGateway.js
CHANGED
|
@@ -717,6 +717,22 @@ class BaseGateway {
|
|
|
717
717
|
filtersAppliedQty += this.applyDeclarativeRemoveFilters(query, filterParams);
|
|
718
718
|
return filtersAppliedQty;
|
|
719
719
|
}
|
|
720
|
+
/**
|
|
721
|
+
* Hook called by count() to apply custom WHERE conditions to the count query.
|
|
722
|
+
*
|
|
723
|
+
* Parallel to onListFilter() — override in subclasses that need filter logic
|
|
724
|
+
* beyond what the declarative countFilters rules can express (OR conditions,
|
|
725
|
+
* subqueries, cross-table joins, etc.).
|
|
726
|
+
*
|
|
727
|
+
* The base implementation is a no-op. Call super.onCountFilter() when
|
|
728
|
+
* overriding so future base-class logic is not silently skipped.
|
|
729
|
+
*
|
|
730
|
+
* @param query Knex query builder for the count query
|
|
731
|
+
* @param filterParams The raw filter object passed to count()
|
|
732
|
+
*/
|
|
733
|
+
onCountFilter(query, filterParams) {
|
|
734
|
+
// no-op — override in subclasses for custom count filter logic
|
|
735
|
+
}
|
|
720
736
|
// ─── Record transforms ─────────────────────────────────────────────────────
|
|
721
737
|
/**
|
|
722
738
|
* Transforms a params object before it is inserted into the database.
|
|
@@ -1310,6 +1326,70 @@ class BaseGateway {
|
|
|
1310
1326
|
}
|
|
1311
1327
|
return items.map((item) => this.transformOnOut(item));
|
|
1312
1328
|
}
|
|
1329
|
+
/**
|
|
1330
|
+
* Returns the count of non-removed rows matching the given filter.
|
|
1331
|
+
*
|
|
1332
|
+
* Applies the same soft-delete, space, and user scoping that list() uses,
|
|
1333
|
+
* ensuring count() and list() always agree on which rows are "visible" for
|
|
1334
|
+
* an identical filter. Uses COUNT(*) — no column data is read, so this is
|
|
1335
|
+
* as cheap as possible on both PostgreSQL and MS Azure SQL.
|
|
1336
|
+
*
|
|
1337
|
+
* Filter application order (mirrors list()):
|
|
1338
|
+
* 1. Soft-delete guard — WHERE Removed_By IS NULL (when hasRemovedBy)
|
|
1339
|
+
* WHERE Removed_At IS NULL (when hasRemovedAt and
|
|
1340
|
+
* not hasRemovedBy — rare, but handled for safety)
|
|
1341
|
+
* 2. Space scoping — WHERE Space_ID = context.spaceId (if hasSpace)
|
|
1342
|
+
* 3. User scoping — WHERE {filterByUserField} = context.userId (if set)
|
|
1343
|
+
* 4. onCountFilter() hook — subclass custom logic
|
|
1344
|
+
* 5. Declarative rules — countFilters when set, otherwise listFilters
|
|
1345
|
+
*
|
|
1346
|
+
* Subclasses that need count with different scoping than list have two options:
|
|
1347
|
+
* A) Set explicit countFilters in the constructor props.
|
|
1348
|
+
* B) Override onCountFilter() for logic that declarative rules cannot express.
|
|
1349
|
+
*
|
|
1350
|
+
* @param filterParams Filter object (same shape as passed to list())
|
|
1351
|
+
* @returns Row count as a number; 0 when nothing matches or on error
|
|
1352
|
+
*/
|
|
1353
|
+
async count(filterParams) {
|
|
1354
|
+
const query = this.getBuilder().count({ qty: '*' });
|
|
1355
|
+
// ── 1. Soft-delete guard ────────────────────────────────────────────────
|
|
1356
|
+
// In this codebase hasRemovedBy and hasRemovedAt are always set together
|
|
1357
|
+
// on the remove path — Removed_By is the primary sentinel. Guard on
|
|
1358
|
+
// Removed_By IS NULL first; fall back to Removed_At IS NULL for tables
|
|
1359
|
+
// that have a timestamp column but no author column (uncommon but valid).
|
|
1360
|
+
if (this.config.hasRemovedBy) {
|
|
1361
|
+
query.whereNull(`${this.config.table}.${constants_1.FIELDS.REMOVED_BY}`);
|
|
1362
|
+
}
|
|
1363
|
+
else if (this.config.hasRemovedAt) {
|
|
1364
|
+
query.whereNull(`${this.config.table}.${constants_1.FIELDS.REMOVED_AT}`);
|
|
1365
|
+
}
|
|
1366
|
+
// ── 2. Space scoping ────────────────────────────────────────────────────
|
|
1367
|
+
if (this.config.hasSpace && this.config.context?.spaceId) {
|
|
1368
|
+
query.where(`${this.config.table}.${constants_1.FIELDS.SPACE_ID}`, this.config.context.spaceId);
|
|
1369
|
+
}
|
|
1370
|
+
// ── 3. User scoping ─────────────────────────────────────────────────────
|
|
1371
|
+
if (this.config.filterByUserField && this.config.context?.userId) {
|
|
1372
|
+
query.where(`${this.config.table}.${this.config.filterByUserField}`, this.config.context.userId);
|
|
1373
|
+
}
|
|
1374
|
+
// ── 4. Subclass hook ────────────────────────────────────────────────────
|
|
1375
|
+
this.onCountFilter(query, filterParams);
|
|
1376
|
+
// ── 5. Declarative filter rules ─────────────────────────────────────────
|
|
1377
|
+
// Fall back to listFilters when countFilters is not explicitly configured.
|
|
1378
|
+
// This means gateways that already declare listFilters get count() for free
|
|
1379
|
+
// with no changes required.
|
|
1380
|
+
const rulesToApply = this.config.countFilters ?? this.config.listFilters ?? [];
|
|
1381
|
+
for (const rule of rulesToApply) {
|
|
1382
|
+
this.applyFilterRule(query, rule, filterParams);
|
|
1383
|
+
}
|
|
1384
|
+
this.logger.debug(`Executing count on table "${this.config.table}"`);
|
|
1385
|
+
const result = (0, utils_1.camelResponse)(await query);
|
|
1386
|
+
const qty = result?.[0]?.qty;
|
|
1387
|
+
if (qty == null) {
|
|
1388
|
+
this.logger.log(`Count query on "${this.config.table}" returned no result row — defaulting to 0`);
|
|
1389
|
+
return 0;
|
|
1390
|
+
}
|
|
1391
|
+
return Number(qty);
|
|
1392
|
+
}
|
|
1313
1393
|
}
|
|
1314
1394
|
exports.BaseGateway = BaseGateway;
|
|
1315
1395
|
// ─── Module-level helpers ──────────────────────────────────────────────────────
|
|
@@ -372,6 +372,20 @@ declare class BaseGateway {
|
|
|
372
372
|
* - `removeFilters` — applies declarative GatewayFilterRule array (new)
|
|
373
373
|
*/
|
|
374
374
|
onRemoveFilter(query: any, filterParams: any): Promise<number>;
|
|
375
|
+
/**
|
|
376
|
+
* Hook called by count() to apply custom WHERE conditions to the count query.
|
|
377
|
+
*
|
|
378
|
+
* Parallel to onListFilter() — override in subclasses that need filter logic
|
|
379
|
+
* beyond what the declarative countFilters rules can express (OR conditions,
|
|
380
|
+
* subqueries, cross-table joins, etc.).
|
|
381
|
+
*
|
|
382
|
+
* The base implementation is a no-op. Call super.onCountFilter() when
|
|
383
|
+
* overriding so future base-class logic is not silently skipped.
|
|
384
|
+
*
|
|
385
|
+
* @param query Knex query builder for the count query
|
|
386
|
+
* @param filterParams The raw filter object passed to count()
|
|
387
|
+
*/
|
|
388
|
+
protected onCountFilter(query: any, filterParams: any): void;
|
|
375
389
|
/**
|
|
376
390
|
* Transforms a params object before it is inserted into the database.
|
|
377
391
|
* Called once per object inside the `create()` loop, after the ID is generated.
|
|
@@ -671,5 +685,30 @@ declare class BaseGateway {
|
|
|
671
685
|
* `transformOnOut()`.
|
|
672
686
|
*/
|
|
673
687
|
remove(where: any): Promise<any[]>;
|
|
688
|
+
/**
|
|
689
|
+
* Returns the count of non-removed rows matching the given filter.
|
|
690
|
+
*
|
|
691
|
+
* Applies the same soft-delete, space, and user scoping that list() uses,
|
|
692
|
+
* ensuring count() and list() always agree on which rows are "visible" for
|
|
693
|
+
* an identical filter. Uses COUNT(*) — no column data is read, so this is
|
|
694
|
+
* as cheap as possible on both PostgreSQL and MS Azure SQL.
|
|
695
|
+
*
|
|
696
|
+
* Filter application order (mirrors list()):
|
|
697
|
+
* 1. Soft-delete guard — WHERE Removed_By IS NULL (when hasRemovedBy)
|
|
698
|
+
* WHERE Removed_At IS NULL (when hasRemovedAt and
|
|
699
|
+
* not hasRemovedBy — rare, but handled for safety)
|
|
700
|
+
* 2. Space scoping — WHERE Space_ID = context.spaceId (if hasSpace)
|
|
701
|
+
* 3. User scoping — WHERE {filterByUserField} = context.userId (if set)
|
|
702
|
+
* 4. onCountFilter() hook — subclass custom logic
|
|
703
|
+
* 5. Declarative rules — countFilters when set, otherwise listFilters
|
|
704
|
+
*
|
|
705
|
+
* Subclasses that need count with different scoping than list have two options:
|
|
706
|
+
* A) Set explicit countFilters in the constructor props.
|
|
707
|
+
* B) Override onCountFilter() for logic that declarative rules cannot express.
|
|
708
|
+
*
|
|
709
|
+
* @param filterParams Filter object (same shape as passed to list())
|
|
710
|
+
* @returns Row count as a number; 0 when nothing matches or on error
|
|
711
|
+
*/
|
|
712
|
+
count(filterParams: any): Promise<number>;
|
|
674
713
|
}
|
|
675
714
|
export { BaseGateway };
|
package/build/esm/BaseGateway.js
CHANGED
|
@@ -2,7 +2,7 @@ import { v4 } from 'uuid';
|
|
|
2
2
|
import dayjs from 'dayjs';
|
|
3
3
|
import check from 'check-types';
|
|
4
4
|
import { camelCase, castArray, pullAll } from 'lodash';
|
|
5
|
-
import { arrToChunks, STATUSES, DateTimeHelpers, buildKey, Logger, LoggerLevels, isLogger } from '@sdflc/utils';
|
|
5
|
+
import { arrToChunks, STATUSES, DateTimeHelpers, buildKey, Logger, LoggerLevels, isLogger, camelResponse, } from '@sdflc/utils';
|
|
6
6
|
import { DataCache } from './DataCache';
|
|
7
7
|
import { FIELDS, ID_FIELD } from './constants';
|
|
8
8
|
const DEFAULT_CHUNCK_SIZE = 2500;
|
|
@@ -711,6 +711,22 @@ class BaseGateway {
|
|
|
711
711
|
filtersAppliedQty += this.applyDeclarativeRemoveFilters(query, filterParams);
|
|
712
712
|
return filtersAppliedQty;
|
|
713
713
|
}
|
|
714
|
+
/**
|
|
715
|
+
* Hook called by count() to apply custom WHERE conditions to the count query.
|
|
716
|
+
*
|
|
717
|
+
* Parallel to onListFilter() — override in subclasses that need filter logic
|
|
718
|
+
* beyond what the declarative countFilters rules can express (OR conditions,
|
|
719
|
+
* subqueries, cross-table joins, etc.).
|
|
720
|
+
*
|
|
721
|
+
* The base implementation is a no-op. Call super.onCountFilter() when
|
|
722
|
+
* overriding so future base-class logic is not silently skipped.
|
|
723
|
+
*
|
|
724
|
+
* @param query Knex query builder for the count query
|
|
725
|
+
* @param filterParams The raw filter object passed to count()
|
|
726
|
+
*/
|
|
727
|
+
onCountFilter(query, filterParams) {
|
|
728
|
+
// no-op — override in subclasses for custom count filter logic
|
|
729
|
+
}
|
|
714
730
|
// ─── Record transforms ─────────────────────────────────────────────────────
|
|
715
731
|
/**
|
|
716
732
|
* Transforms a params object before it is inserted into the database.
|
|
@@ -1304,6 +1320,70 @@ class BaseGateway {
|
|
|
1304
1320
|
}
|
|
1305
1321
|
return items.map((item) => this.transformOnOut(item));
|
|
1306
1322
|
}
|
|
1323
|
+
/**
|
|
1324
|
+
* Returns the count of non-removed rows matching the given filter.
|
|
1325
|
+
*
|
|
1326
|
+
* Applies the same soft-delete, space, and user scoping that list() uses,
|
|
1327
|
+
* ensuring count() and list() always agree on which rows are "visible" for
|
|
1328
|
+
* an identical filter. Uses COUNT(*) — no column data is read, so this is
|
|
1329
|
+
* as cheap as possible on both PostgreSQL and MS Azure SQL.
|
|
1330
|
+
*
|
|
1331
|
+
* Filter application order (mirrors list()):
|
|
1332
|
+
* 1. Soft-delete guard — WHERE Removed_By IS NULL (when hasRemovedBy)
|
|
1333
|
+
* WHERE Removed_At IS NULL (when hasRemovedAt and
|
|
1334
|
+
* not hasRemovedBy — rare, but handled for safety)
|
|
1335
|
+
* 2. Space scoping — WHERE Space_ID = context.spaceId (if hasSpace)
|
|
1336
|
+
* 3. User scoping — WHERE {filterByUserField} = context.userId (if set)
|
|
1337
|
+
* 4. onCountFilter() hook — subclass custom logic
|
|
1338
|
+
* 5. Declarative rules — countFilters when set, otherwise listFilters
|
|
1339
|
+
*
|
|
1340
|
+
* Subclasses that need count with different scoping than list have two options:
|
|
1341
|
+
* A) Set explicit countFilters in the constructor props.
|
|
1342
|
+
* B) Override onCountFilter() for logic that declarative rules cannot express.
|
|
1343
|
+
*
|
|
1344
|
+
* @param filterParams Filter object (same shape as passed to list())
|
|
1345
|
+
* @returns Row count as a number; 0 when nothing matches or on error
|
|
1346
|
+
*/
|
|
1347
|
+
async count(filterParams) {
|
|
1348
|
+
const query = this.getBuilder().count({ qty: '*' });
|
|
1349
|
+
// ── 1. Soft-delete guard ────────────────────────────────────────────────
|
|
1350
|
+
// In this codebase hasRemovedBy and hasRemovedAt are always set together
|
|
1351
|
+
// on the remove path — Removed_By is the primary sentinel. Guard on
|
|
1352
|
+
// Removed_By IS NULL first; fall back to Removed_At IS NULL for tables
|
|
1353
|
+
// that have a timestamp column but no author column (uncommon but valid).
|
|
1354
|
+
if (this.config.hasRemovedBy) {
|
|
1355
|
+
query.whereNull(`${this.config.table}.${FIELDS.REMOVED_BY}`);
|
|
1356
|
+
}
|
|
1357
|
+
else if (this.config.hasRemovedAt) {
|
|
1358
|
+
query.whereNull(`${this.config.table}.${FIELDS.REMOVED_AT}`);
|
|
1359
|
+
}
|
|
1360
|
+
// ── 2. Space scoping ────────────────────────────────────────────────────
|
|
1361
|
+
if (this.config.hasSpace && this.config.context?.spaceId) {
|
|
1362
|
+
query.where(`${this.config.table}.${FIELDS.SPACE_ID}`, this.config.context.spaceId);
|
|
1363
|
+
}
|
|
1364
|
+
// ── 3. User scoping ─────────────────────────────────────────────────────
|
|
1365
|
+
if (this.config.filterByUserField && this.config.context?.userId) {
|
|
1366
|
+
query.where(`${this.config.table}.${this.config.filterByUserField}`, this.config.context.userId);
|
|
1367
|
+
}
|
|
1368
|
+
// ── 4. Subclass hook ────────────────────────────────────────────────────
|
|
1369
|
+
this.onCountFilter(query, filterParams);
|
|
1370
|
+
// ── 5. Declarative filter rules ─────────────────────────────────────────
|
|
1371
|
+
// Fall back to listFilters when countFilters is not explicitly configured.
|
|
1372
|
+
// This means gateways that already declare listFilters get count() for free
|
|
1373
|
+
// with no changes required.
|
|
1374
|
+
const rulesToApply = this.config.countFilters ?? this.config.listFilters ?? [];
|
|
1375
|
+
for (const rule of rulesToApply) {
|
|
1376
|
+
this.applyFilterRule(query, rule, filterParams);
|
|
1377
|
+
}
|
|
1378
|
+
this.logger.debug(`Executing count on table "${this.config.table}"`);
|
|
1379
|
+
const result = camelResponse(await query);
|
|
1380
|
+
const qty = result?.[0]?.qty;
|
|
1381
|
+
if (qty == null) {
|
|
1382
|
+
this.logger.log(`Count query on "${this.config.table}" returned no result row — defaulting to 0`);
|
|
1383
|
+
return 0;
|
|
1384
|
+
}
|
|
1385
|
+
return Number(qty);
|
|
1386
|
+
}
|
|
1307
1387
|
}
|
|
1308
1388
|
export { BaseGateway };
|
|
1309
1389
|
// ─── Module-level helpers ──────────────────────────────────────────────────────
|
|
@@ -165,4 +165,21 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
165
165
|
* ]
|
|
166
166
|
*/
|
|
167
167
|
removeFilters?: GatewayFilterRule[];
|
|
168
|
+
/**
|
|
169
|
+
* Declarative WHERE rules applied by count() after base scoping logic.
|
|
170
|
+
*
|
|
171
|
+
* When not explicitly set, count() falls back to listFilters — in most
|
|
172
|
+
* cases count and list should be scoped identically for the same filter
|
|
173
|
+
* params. Set countFilters explicitly only when count needs different
|
|
174
|
+
* scoping than list (e.g. counting across statuses that list excludes).
|
|
175
|
+
*
|
|
176
|
+
* All filter types are supported ('search', 'dateRange', 'nullableDateRange'
|
|
177
|
+
* included) — count() is a read operation, same as list().
|
|
178
|
+
*
|
|
179
|
+
* Example:
|
|
180
|
+
* countFilters: [
|
|
181
|
+
* { field: 'partyId', column: 'Party_Guest.Party_ID', type: 'array' },
|
|
182
|
+
* ]
|
|
183
|
+
*/
|
|
184
|
+
countFilters?: GatewayFilterRule[];
|
|
168
185
|
}
|
|
@@ -165,4 +165,21 @@ export interface BaseGatewayPropsInterface extends CacheInterface {
|
|
|
165
165
|
* ]
|
|
166
166
|
*/
|
|
167
167
|
removeFilters?: GatewayFilterRule[];
|
|
168
|
+
/**
|
|
169
|
+
* Declarative WHERE rules applied by count() after base scoping logic.
|
|
170
|
+
*
|
|
171
|
+
* When not explicitly set, count() falls back to listFilters — in most
|
|
172
|
+
* cases count and list should be scoped identically for the same filter
|
|
173
|
+
* params. Set countFilters explicitly only when count needs different
|
|
174
|
+
* scoping than list (e.g. counting across statuses that list excludes).
|
|
175
|
+
*
|
|
176
|
+
* All filter types are supported ('search', 'dateRange', 'nullableDateRange'
|
|
177
|
+
* included) — count() is a read operation, same as list().
|
|
178
|
+
*
|
|
179
|
+
* Example:
|
|
180
|
+
* countFilters: [
|
|
181
|
+
* { field: 'partyId', column: 'Party_Guest.Party_ID', type: 'array' },
|
|
182
|
+
* ]
|
|
183
|
+
*/
|
|
184
|
+
countFilters?: GatewayFilterRule[];
|
|
168
185
|
}
|