@ethlete/query 6.0.0-next.51 → 6.0.0-next.52

package/migrations/query-field-default-types.md

@@ -0,0 +1,43 @@
+# `queryField<T>()` is typed by its default and reads the URL into that type
+
+`queryField<T>()` used to be typed `T | null` whatever its default, and guessed the type of a URL
+value: `?id=123` became the number `123` even in a `queryField<string>()`. Now:
+
+- A field with a non-null `defaultValue` is typed `T`, and a reset or an unreadable URL value falls
+  back to the default.
+- A URL value is read into the type of the default (number, boolean, string, string list). Without a
+  default it stays a string.
+- Any other `T` needs a `queryParamToValue`: `queryField<number>()` without a default, a `Date` or an
+  object default.
+- `searchQueryField()` and `sortQueryField()` no longer count in `activeFilterCount`, whatever their key.
+
+The type check finds every call site that has to change.
+
+## Find the call sites
+
+```bash
+grep -rnE '\bqueryField<' apps libs --include='*.ts'
+```
+
+## What to change
+
+1. `queryField<number>()` or `queryField<boolean>()` without a default: give it the `defaultValue` it
+   effectively had, or add `queryParamToValue: transformToNumber` (`transformToBoolean`, …) and keep
+   the `null` start. Both transforms are exported from `@ethlete/query`.
+2. A `Date` or object default without a `queryParamToValue`: add one (`transformToDate` for a date).
+3. A field that must hold `null` beside a non-null default - an explicit "none" - is declared
+   `queryField<T | null>({ defaultValue: … })`.
+4. Delete the `?? DEFAULT` on reads of a field that now has a non-null type, and any `!` or cast that
+   only existed to strip `null`.
+5. A field bound to a native `<input type="number">` is declared `number | null`: the input writes
+   `null` when cleared.
+6. A field that relied on the old guess - a `queryField<string>()` read as a number somewhere - gets
+   the type it was really used as.
+7. A UI that counted a search or sort field as a filter: pass `skipInFilterCount: false` to keep it.
+
+## When you are done
+
+Run the type check, the lint task and the tests of every project you changed, and check in the
+browser that a reload restores each list.
+
+The query forms guide is at <https://ethlete-sdk-docs.web.app/query/query-forms>.

package/migrations/search-query-field-string.md

@@ -0,0 +1,43 @@
+# `searchQueryField()` is a `string` that starts at `''`
+
+`searchQueryField()` used to be typed `string | null` and start at `null`. It is typed `string` now and
+starts at `''`, so `[formField]` binds it to `<et-input>` under `strictTemplates`. An empty search still
+writes no URL param, so URLs do not change. The type check finds most call sites; a comparison with
+`null` compiles and silently stops matching.
+
+## Find the call sites
+
+```bash
+grep -rnE 'searchQueryField\(' apps libs --include='*.ts' -l
+```
+
+In each file found, and in each file that reads the form's value, look for the search field's key
+(`search`, `query`, `q`, …) next to `null`:
+
+```bash
+grep -rnE '(search|query|q)\b[^;]*(null|\?\?)' apps libs --include='*.ts'
+```
+
+## What to change
+
+1. A write of `null` - `setValue({ search: null, … })`, `patchValue({ search: null })`, a seed object,
+   a test fixture - writes `''` instead.
+2. A check for an empty search - `search === null`, `search !== null`, `search == null`,
+   `search ?? ''` - becomes `search === ''`, `search !== ''`, or just `search`. `?? ''` is dead code
+   now; delete it.
+3. A search that goes into a request body or GraphQL variables passes `search || null` where the API
+   expects `null` for "no search". Query params need nothing: the client drops an empty string.
+4. A type that restates the value, such as `search: string | null` in an interface built from the
+   form, becomes `string`. Prefer deriving it from `ReturnType<typeof qf.value>`.
+5. A test that expects `null` for an empty search expects `''`.
+
+## Leave these alone
+
+- `queryField<string>()` fields. They still start at `null`.
+- The legacy `SearchQueryField` class. It is unchanged.
+
+## When you are done
+
+Run the type check, the lint task and the tests of every project you changed.
+
+The query forms guide is at <https://ethlete-sdk-docs.web.app/query/query-forms>.

package/migrations.json

@@ -39,6 +39,22 @@
       "description": "Mark the remaining createLegacyQueryCreator wrappers as deprecated, so their call sites surface as still on v2.",
       "generator": "@ethlete/query:deprecate-legacy-queries",
       "docs": "/query/legacy"
+    },
+    {
+      "name": "search-query-field-string",
+      "version": "6.0.0-next.52",
+      "kind": "assisted",
+      "description": "searchQueryField() is typed string and starts at '' instead of null; writes and checks of null move to ''.",
+      "instructions": "./migrations/search-query-field-string.md",
+      "docs": "/query/query-forms"
+    },
+    {
+      "name": "query-field-default-types",
+      "version": "6.0.0-next.52",
+      "kind": "assisted",
+      "description": "queryField() is typed by its default and reads the URL into that type; fields without a default or with a non-primitive one need a queryParamToValue.",
+      "instructions": "./migrations/query-field-default-types.md",
+      "docs": "/query/query-forms"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.51",
+  "version": "6.0.0-next.52",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
@@ -44,6 +44,10 @@
       "types": "./types/ethlete-query.d.ts",
       "default": "./fesm2022/ethlete-query.mjs"
     },
+    "./ngrx-toolkit": {
+      "types": "./types/ethlete-query-ngrx-toolkit.d.ts",
+      "default": "./fesm2022/ethlete-query-ngrx-toolkit.mjs"
+    },
     "./testing": {
       "types": "./types/ethlete-query-testing.d.ts",
       "default": "./fesm2022/ethlete-query-testing.mjs"

package/types/ethlete-query-ngrx-toolkit.d.ts

@@ -0,0 +1,143 @@
+import * as i0 from '@angular/core';
+import { PipeTransform, Injector } from '@angular/core';
+import { Observable, Subject } from 'rxjs';
+import { AnyQueryCreator, QueryArgsOf, QueryHeaders, ResponseType } from '@ethlete/query';
+
+/** The call state of a toolkit handle, as `@tomtomb/ngrx-toolkit` names it. */
+declare const CallState: {
+    readonly INIT: "INIT";
+    readonly LOADING: "LOADING";
+    readonly SUCCESS: "SUCCESS";
+    readonly ERROR: "ERROR";
+};
+type CallState = (typeof CallState)[keyof typeof CallState];
+/** The error shape of `@tomtomb/ngrx-toolkit`: the HTTP status, the error message and the response body. */
+type ToolkitError<T = unknown> = {
+    status: number | string;
+    message: string;
+    data: T | null;
+};
+type ToolkitActionOptions = {
+    headers?: QueryHeaders;
+    extras?: {
+        skipCache?: boolean;
+    };
+};
+/**
+ * The toolkit-shaped args of a query creator: `queryParams` holds the path params, `params` the query string and
+ * `body` the body, the way `@tomtomb/ngrx-toolkit` action groups named them.
+ */
+type ActionCallArgs<TCreator extends AnyQueryCreator> = {
+    [K in keyof QueryArgsOf<TCreator> as K extends 'pathParams' ? 'queryParams' : K extends 'queryParams' ? 'params' : K extends 'body' ? 'body' : never]: QueryArgsOf<TCreator>[K];
+} & {
+    actionOptions?: ToolkitActionOptions;
+};
+type ToolkitPollingOptions = {
+    intervalDuration: number;
+    killSwitch: Subject<boolean>;
+};
+/** The handle `toolkitCall` returns, shaped like the `MappedEntityState` of `@tomtomb/ngrx-toolkit`. */
+type MappedEntityState<TCreator extends AnyQueryCreator> = {
+    response$: Observable<ResponseType<QueryArgsOf<TCreator>> | null>;
+    cachedResponse$: Observable<ResponseType<QueryArgsOf<TCreator>>>;
+    error$: Observable<ToolkitError | null>;
+    args$: Observable<ActionCallArgs<TCreator> | null>;
+    isInit$: Observable<boolean | null>;
+    isLoading$: Observable<boolean | null>;
+    isSuccess$: Observable<boolean | null>;
+    isError$: Observable<boolean | null>;
+    timestamp$: Observable<number | null>;
+    callState$: Observable<CallState | null>;
+    refresh: () => void;
+    remove: () => void;
+    startPolling: (options: ToolkitPollingOptions) => void;
+    stopPolling: () => void;
+};
+type AnyMappedEntityState = MappedEntityState<any>;
+
+type ExtractFrom<T> = T extends Observable<infer U> ? U : never;
+/** What `suspense` and `suspenseMulti` render for a handle: every stream's current value, plus the handle's methods. */
+type ToolkitSuspenseState<T extends AnyMappedEntityState | null | undefined> = T extends AnyMappedEntityState ? {
+    args: ExtractFrom<T['args$']>;
+    cachedResponse: ExtractFrom<T['cachedResponse$']> | null;
+    callState: ExtractFrom<T['callState$']>;
+    error: ExtractFrom<T['error$']>;
+    isError: ExtractFrom<T['isError$']>;
+    isInit: ExtractFrom<T['isInit$']>;
+    isLoading: ExtractFrom<T['isLoading$']>;
+    isSuccess: ExtractFrom<T['isSuccess$']>;
+    response: ExtractFrom<T['response$']>;
+    timestamp: ExtractFrom<T['timestamp$']>;
+    refresh: () => void;
+    remove: () => void;
+    startPolling: (options: ToolkitPollingOptions) => void;
+    stopPolling: () => void;
+} : T;
+/** Subscribes to a toolkit handle and renders its current state, like the `suspense` pipe of `@tomtomb/ngrx-toolkit`. */
+declare class SuspensePipe implements PipeTransform {
+    transform: <T extends AnyMappedEntityState>(value: T | null | undefined) => ToolkitSuspenseState<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SuspensePipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SuspensePipe, "suspense", true>;
+}
+
+type AnyHandleRecord = Record<string, AnyMappedEntityState | null | undefined>;
+type ToolkitSuspenseMultiState<T extends AnyHandleRecord> = {
+    [K in keyof T]: ToolkitSuspenseState<T[K]>;
+};
+/**
+ * Subscribes to a record of toolkit handles and renders each one's current state, like the `suspenseMulti` pipe of
+ * `@tomtomb/ngrx-toolkit`. Nothing renders until every non-null handle has emitted.
+ */
+declare class SuspenseMultiPipe implements PipeTransform {
+    transform: <T extends AnyHandleRecord>(value: T | null | undefined) => ToolkitSuspenseMultiState<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SuspenseMultiPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SuspenseMultiPipe, "suspenseMulti", true>;
+}
+
+/** Exports the `suspense` and `suspenseMulti` pipes, like the `NgRxToolkitModule` of `@tomtomb/ngrx-toolkit`. */
+declare class NgRxToolkitModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgRxToolkitModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgRxToolkitModule, never, [typeof SuspensePipe, typeof SuspenseMultiPipe], [typeof SuspensePipe, typeof SuspenseMultiPipe]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<NgRxToolkitModule>;
+}
+
+type ToolkitCallOptions = {
+    /**
+     * The injector the handle's query lives in. Required outside an injection context, which is where a
+     * `providedIn: 'root'` facade calls from; pass the facade's `inject(Injector)`.
+     */
+    injector?: Injector;
+};
+/**
+ * Returns the handle for a creator and args without executing it - the `FacadeBase.select(group, actionId)` of
+ * `@tomtomb/ngrx-toolkit`. Args that build the same request (in any key order, other keys ignored) give the same
+ * handle `toolkitCall` returns, so `toolkitSelect(getTeam, args, { injector }).refresh()` re-runs a request another
+ * component started.
+ */
+declare const toolkitSelect: <TCreator extends AnyQueryCreator>(creator: TCreator, args: ActionCallArgs<TCreator>, options?: ToolkitCallOptions) => MappedEntityState<TCreator>;
+/**
+ * Executes a query creator with toolkit-shaped args and returns its handle - the `FacadeBase.call(group, args)` of
+ * `@tomtomb/ngrx-toolkit`. Every call sends the request again; equal args return the same handle, which lives as
+ * long as the injector.
+ *
+ * @example
+ * ```ts
+ * @Injectable({ providedIn: 'root' })
+ * export class TeamFacade {
+ *   private injector = inject(Injector);
+ *
+ *   getTeam(args: ActionCallArgs<typeof getTeam>) {
+ *     return toolkitCall(getTeam, args, { injector: this.injector });
+ *   }
+ * }
+ * ```
+ */
+declare const toolkitCall: <TCreator extends AnyQueryCreator>(creator: TCreator, args: ActionCallArgs<TCreator>, options?: ToolkitCallOptions) => MappedEntityState<TCreator>;
+
+/** Emits `true` while any of the given loading streams is `true`. Nullish entries are skipped. */
+declare const joinLoading: (observables: (Observable<boolean | null> | null | undefined)[]) => Observable<boolean>;
+/** Emits every non-null error of the given error streams, or `null` when there is none. Nullish entries are skipped. */
+declare const joinErrors: (observables: (Observable<ToolkitError | null> | null | undefined)[]) => Observable<ToolkitError[] | null>;
+
+export { CallState, NgRxToolkitModule, SuspenseMultiPipe, SuspensePipe, joinErrors, joinLoading, toolkitCall, toolkitSelect };
+export type { ActionCallArgs, AnyMappedEntityState, MappedEntityState, ToolkitActionOptions, ToolkitCallOptions, ToolkitError, ToolkitPollingOptions, ToolkitSuspenseMultiState, ToolkitSuspenseState };