@ethlete/query 5.23.0 → 5.25.0

package/lib/experimental/http/query-features.d.ts

@@ -0,0 +1,120 @@
+import { HttpErrorResponse, HttpEvent } from '@angular/common/http';
+import { Signal } from '@angular/core';
+import { QueryArgs, RequestArgs, ResponseType } from './query';
+import { QueryDependencies } from './query-dependencies';
+import { InternalQueryExecute } from './query-execute';
+import { QueryState } from './query-state';
+import { ClearQueryArgs, QueryFeatureFlags } from './query-utils';
+export declare const enum QueryFeatureType {
+    WithArgs = "withArgs",
+    WithLogging = "withLogging",
+    WithErrorHandling = "withErrorHandling",
+    WithSuccessHandling = "withSuccessHandling",
+    WithPolling = "withPolling",
+    WithAutoRefresh = "withAutoRefresh",
+    WithResponseUpdate = "withResponseUpdate"
+}
+export type QueryFeatureContext<TArgs extends QueryArgs> = {
+    state: QueryState<TArgs>;
+    execute: InternalQueryExecute<TArgs>;
+    deps: QueryDependencies;
+    flags: QueryFeatureFlags;
+};
+export type QueryFeatureFn<TArgs extends QueryArgs> = (context: QueryFeatureContext<TArgs>) => void;
+export type QueryFeature<TArgs extends QueryArgs> = {
+    type: QueryFeatureType;
+    fn: (context: QueryFeatureContext<TArgs>) => void;
+};
+/**
+ * A query feature that allows you to set the arguments of the query.
+ * The arguments are read within a computed function, so you can use reactive values.
+ *
+ * To set the arguments to `null`, return the symbol `CLEAR_QUERY_ARGS`.
+ * If you instead return `null`, the arguments won't change.
+ *
+ * Changing arguments will automatically trigger a new execution of the query if it is eligible for auto execution (e.g. a GET request).
+ */
+export declare const withArgs: <TArgs extends QueryArgs>(args: () => NoInfer<RequestArgs<TArgs>> | ClearQueryArgs | null) => QueryFeature<TArgs>;
+export type WithPollingFeatureOptions = {
+    /** The interval in milliseconds at which the query should be executed */
+    interval: number;
+    /**
+     * Whether the query should be executed initially.
+     * By default, the query will be executed after the first interval.
+     * @default false
+     */
+    executeInitially?: boolean;
+};
+/**
+ * A query feature that will automatically execute the query at a given interval.
+ * The interval will be cleared when the query is destroyed.
+ * The interval will be reset when the arguments of the query change.
+ *
+ * @throws If the query is not eligible for auto execution (e.g. a POST request)
+ */
+export declare const withPolling: <TArgs extends QueryArgs>(options: WithPollingFeatureOptions) => QueryFeature<TArgs>;
+export type WithLoggingFeatureOptions<TArgs extends QueryArgs> = {
+    /** A function that will be called with the latest http event */
+    logFn: (v: HttpEvent<ResponseType<TArgs>> | null) => void;
+};
+/** A query feature that can be used to log the latest http event */
+export declare const withLogging: <TArgs extends QueryArgs>(options: WithLoggingFeatureOptions<TArgs>) => QueryFeature<TArgs>;
+export type WithErrorHandlingFeatureOptions = {
+    /** A function that will be called with the latest error */
+    handler: (e: HttpErrorResponse) => void;
+};
+/** A query feature that can be used to handle errors */
+export declare const withErrorHandling: <TArgs extends QueryArgs>(options: WithErrorHandlingFeatureOptions) => QueryFeature<TArgs>;
+type WithSuccessHandlingFeatureOptions<TArgs extends QueryArgs> = {
+    /** A function that will be called with the latest response */
+    handler: (data: NonNullable<ResponseType<TArgs>>) => void;
+};
+/** A query feature that can be used to handle successful responses */
+export declare const withSuccessHandling: <TArgs extends QueryArgs>(options: WithSuccessHandlingFeatureOptions<TArgs>) => QueryFeature<TArgs>;
+export type WithAutoRefreshFeatureOptions = {
+    /** The signals that should trigger a refresh of the query */
+    onSignalChanges: Signal<unknown>[];
+    /** Whether to ignore the `onlyManualExecution` query config flag */
+    ignoreOnlyManualExecution?: boolean;
+};
+/**
+ * A query feature that will automatically execute the query when any of the provided signals change
+ * @throws If the query is not eligible for auto execution (e.g. a POST request)
+ * @throws If the query has the `onlyManualExecution` query config flag set and `ignoreOnlyManualExecution` is not set
+ */
+export declare const withAutoRefresh: <TArgs extends QueryArgs>(options: WithAutoRefreshFeatureOptions) => QueryFeature<TArgs>;
+export type WithResponseUpdateFeatureFnData<TArgs extends QueryArgs> = {
+    /** The current response of the query */
+    currentResponse: ResponseType<TArgs> | null;
+};
+export type WithResponseUpdateFeatureOptions<TArgs extends QueryArgs> = {
+    /**
+     * A function that will be called with the latest response
+     * If the function returns `null`, the response will not be updated.
+     * Otherwise, the response will be updated with the returned value.
+     * The function will be called in a reactive signal context.
+     * If the query get's executed after the response was updated, the response will be set the the fresh data received from the server.
+     *
+     * This feature is most useful in combination with web sockets where the data received from the socket might be more up-to-date than the data received previously.
+     *
+     * @example
+     * const matchEvents = mySocket.joinRoom('match-events');
+     *
+     * const myMatchQuery = getMatch(
+     *  withArgs(() => ({ matchId: 1 })),
+     *  withResponseUpdate(({ currentResponse }) => {
+     *   const matchEvent = matchEvents();
+     *
+     *   if (!matchEvent) return null;
+     *
+     *   // Do some checks here. This is just a very simple example.
+     *   // To apply partial updates, you can use the spread operator in combination with the current response.
+     *
+     *   return matchEvent;
+     *  })
+     * )
+     */
+    updater: (data: WithResponseUpdateFeatureFnData<TArgs>) => ResponseType<TArgs> | null;
+};
+export declare const withResponseUpdate: <TArgs extends QueryArgs>(options: WithResponseUpdateFeatureOptions<TArgs>) => QueryFeature<TArgs>;
+export {};

package/lib/experimental/{query-repository.d.ts → http/query-repository.d.ts}

@@ -3,7 +3,7 @@ import { CreateHttpRequestClientOptions, HttpRequest } from './http-request';
 import { QueryArgs, RequestArgs } from './query';
 import { QueryClientConfig } from './query-client-config';
 import { QueryMethod, RouteType } from './query-creator';
-import { RunQueryExecuteOptions } from './query-execute-utils';
+import { InternalRunQueryExecuteOptions, RunQueryExecuteOptions } from './query-execute-utils';
 export type QueryRepositoryRequestOptions<TArgs extends QueryArgs> = {
     /**
      * The route of the request.
@@ -25,6 +25,8 @@ export type QueryRepositoryRequestOptions<TArgs extends QueryArgs> = {
     destroyRef: DestroyRef;
     /** Configuration on how to run the query */
     runQueryOptions?: RunQueryExecuteOptions;
+    /** Internal options for running the query */
+    internalRunQueryOptions?: InternalRunQueryExecuteOptions;
 };
 export type QueryRepositoryItem<TArgs extends QueryArgs> = {
     /** The key of the request. If the key is `false`, the request is not cached, otherwise it is. */

package/lib/experimental/{query-snapshot.d.ts → http/query-snapshot.d.ts}

@@ -1,10 +1,10 @@
 import { QueryArgs, QuerySnapshot } from './query';
 import { QueryDependencies } from './query-dependencies';
-import { QueryExecute } from './query-execute';
+import { InternalQueryExecute } from './query-execute';
 import { QueryState } from './query-state';
 export type CreateQuerySnapshotOptions<TArgs extends QueryArgs> = {
     state: QueryState<TArgs>;
     deps: QueryDependencies;
-    execute: QueryExecute<TArgs>;
+    execute: InternalQueryExecute<TArgs>;
 };
 export declare const createQuerySnapshotFn: <TArgs extends QueryArgs>(options: CreateQuerySnapshotOptions<TArgs>) => () => QuerySnapshot<TArgs>;

package/lib/experimental/http/query-stack.d.ts

@@ -0,0 +1,101 @@
+import { HttpErrorResponse } from '@angular/common/http';
+import { Signal } from '@angular/core';
+import { AnyQuery, RequestArgs, ResponseType } from './query';
+import { AnyQueryCreator, QueryArgsOf, RunQueryCreator } from './query-creator';
+import { QueryFeature } from './query-features';
+export type QueryStack<TQuery extends AnyQuery, TTransform> = {
+    /** Contains all queries in the stack. */
+    queries: Signal<TQuery[]>;
+    /** Contains the last query in the stack. Useful for getting current pagination values. */
+    lastQuery: Signal<TQuery | null>;
+    /** True if any query in the stack is loading. */
+    loading: Signal<boolean>;
+    /** Contains the first error that occurred in the stack. */
+    error: Signal<HttpErrorResponse | null>;
+    /** Contains the responses of all queries in the stack. Will be `null` for queries that are loading or errored. */
+    response: Signal<TTransform>;
+    /** Executes all queries in the stack. */
+    execute: (options?: {
+        allowCache?: boolean;
+    }) => void;
+    /** Destroys all queries in the stack and empties it. This should only be used if `append` is true. */
+    clear: () => void;
+};
+export type AnyQueryStack = QueryStack<AnyQuery, any>;
+export type CreateQueryStackOptions<TCreator extends AnyQueryCreator, TDeps extends () => any, TTransform = (ResponseType<QueryArgsOf<TCreator>> | null)[]> = {
+    /**
+     * The query creator function that will be used to create the query stack.
+     */
+    queryCreator: TCreator;
+    /**
+     * The dependencies that should trigger a new query stack creation.
+     * This function can be treated like a computed function. It reacts to signal changes.
+     * The return value of this function will be passed to the `args` function.
+     *
+     * This option can be ignored if `append` is false.
+     */
+    dependencies?: TDeps;
+    /**
+     * The features that should be used for all queries in the stack.
+     *
+     * @throws If the `withArgs` feature is used. This feature is internally used.
+     *
+     * @example
+     * // Due to limitations in TypeScript, you have to manually add the needed generic types if needed.
+     * features: [E.withSuccessHandling<GetPostQueryArgs>({ handler: (post) => console.log(post.title) })]
+     *
+     * @example
+     * // If typings are not needed, you can use the feature without generics.
+     * features: [E.withPolling({ interval: 5000 })]
+     */
+    features?: QueryFeature<any>[];
+    /**
+     * The arguments to create queries with.
+     * This function can be treated like a computed function. It reacts to signal changes.
+     * If a signal changes, a new query will be created (and appended to the existing ones if `append` is true).
+     * If this function returns `null`, the args will be ignored.
+     * If this function returns an array, multiple queries will be created.
+     *
+     * @example
+     * // One query
+     * () => ({ queryParams: { postId: myId() } }),
+     *
+     * @example
+     * // Multiple queries (these can of cause also be created using a loop)
+     * () => [
+     *  { queryParams: { postId: myId() } },
+     *  { queryParams: { postId: myOtherId() } },
+     * ],
+     *
+     * @example
+     * // One query with dependencies
+     * (deps) => ({ queryParams: { postId: myId(), limit: deps.limit } }),
+     */
+    args: (deps: ReturnType<TDeps>) => RequestArgs<QueryArgsOf<TCreator>> | RequestArgs<QueryArgsOf<TCreator>>[] | null;
+    /**
+     * If true, new queries will be appended to the existing ones. Otherwise, existing queries will be destroyed.
+     * This should be used for things like infinite scrolling where already fetched queries should not be destroyed.
+     */
+    append?: boolean;
+    /**
+     * If append is true, this function will be called to merge the old and new queries.
+     * Useful if you want to append the new queries in a specific order (e.g. at the beginning).
+     */
+    appendFn?: (oldQueries: RunQueryCreator<TCreator>[], newQueries: RunQueryCreator<TCreator>[]) => {
+        /** The new queries merged with the old ones. */
+        queries: RunQueryCreator<TCreator>[];
+        /** The last query in the new queries. */
+        lastQuery: RunQueryCreator<TCreator> | null;
+    };
+    /**
+     * Transforms the responses of all queries in the stack. Useful for merging or filtering responses.
+     */
+    transform?: (responses: ResponseType<QueryArgsOf<TCreator>>[]) => TTransform;
+};
+/** Transforms an array of arrays into a single array and filters out `null` values. */
+export declare const transformArrayResponse: <T extends (unknown | null)[]>(responses: T) => NonNullable<T[0]>[];
+/** Transforms an array of paginated responses into a single array and filters out `null` values. */
+export declare const transformPaginatedResponse: <T extends ({
+    items: unknown[];
+} | null)[]>(responses: T) => NonNullable<NonNullable<T[0]>["items"]>;
+export declare const createQueryStack: <TCreator extends AnyQueryCreator, TArgs extends QueryArgsOf<TCreator>, TDeps extends () => any, TTransform = (ResponseType<TArgs> | null)[]>(options: CreateQueryStackOptions<TCreator, TDeps, TTransform>) => QueryStack<RunQueryCreator<TCreator>, TTransform>;

package/lib/experimental/{query-state.d.ts → http/query-state.d.ts}

@@ -1,8 +1,11 @@
 import { HttpErrorResponse, HttpEvent } from '@angular/common/http';
 import { WritableSignal } from '@angular/core';
-import { HttpRequestLoadingState } from './http-request';
+import { HttpRequest, HttpRequestLoadingState } from './http-request';
 import { QueryArgs, RequestArgs, ResponseType } from './query';
 export type SetupQueryStateOptions = {};
+export type QueryStateSubtle<TArgs extends QueryArgs> = {
+    request: WritableSignal<HttpRequest<TArgs> | null>;
+};
 export type QueryState<TArgs extends QueryArgs> = {
     response: WritableSignal<ResponseType<TArgs> | null>;
     args: WritableSignal<RequestArgs<TArgs> | null>;
@@ -10,5 +13,6 @@ export type QueryState<TArgs extends QueryArgs> = {
     loading: WritableSignal<HttpRequestLoadingState | null>;
     error: WritableSignal<HttpErrorResponse | null>;
     lastTimeExecutedAt: WritableSignal<number | null>;
+    subtle: QueryStateSubtle<TArgs>;
 };
 export declare const setupQueryState: <TArgs extends QueryArgs>(options: SetupQueryStateOptions) => QueryState<TArgs>;

package/lib/experimental/{query-utils.d.ts → http/query-utils.d.ts}

@@ -1,20 +1,25 @@
 import { HttpErrorResponse, HttpHeaders } from '@angular/common/http';
-import { CreateEffectOptions } from '@angular/core';
-import { CreateQueryOptions, Query, QueryArgs, QuerySnapshot } from './query';
+import { CreateEffectOptions, Signal } from '@angular/core';
+import { CreateGqlQueryOptions } from '../gql/gql-query';
+import { GqlQueryMethod } from '../gql/gql-query-creator';
+import { CreateQueryOptions, Query, QueryArgs, RequestArgs } from './query';
 import { QueryMethod } from './query-creator';
-import { QueryExecute } from './query-execute';
-import { QueryFeatureContext } from './query-features';
+import { QueryDependencies } from './query-dependencies';
+import { InternalQueryExecute } from './query-execute';
+import { QueryFeature, QueryFeatureContext } from './query-features';
+import { QueryKeyOrNone } from './query-repository';
 import { QueryState } from './query-state';
 /**
- * Returning this inside e.g. a withComputedArgs feature will reset the query args to null.
+ * Returning this inside a withArgs feature will reset the query args to null.
  * This will also pause polling and auto refresh until new args are set.
  */
-export declare const QUERY_ARGS_RESET: unique symbol;
-export type QueryArgsReset = typeof QUERY_ARGS_RESET;
+export declare const CLEAR_QUERY_ARGS: unique symbol;
+export type ClearQueryArgs = typeof CLEAR_QUERY_ARGS;
 export declare const QUERY_EFFECT_ERROR_MESSAGE = "Effect triggered too often. This is probably due to a circular dependency inside the query.";
 /** A angular effect that will throw an error in dev mode if it is called too often. This indicates a circular dependency inside the effect. */
-export declare const queryEffect: (fn: () => void, errorMessage: string, options?: CreateEffectOptions) => import("@angular/core").EffectRef;
+export declare const queryEffect: (fn: (isFirstRun: boolean) => void, errorMessage: string, options?: CreateEffectOptions) => import("@angular/core").EffectRef;
 export declare const shouldAutoExecuteQuery: (method: QueryMethod) => method is "GET" | "HEAD" | "OPTIONS";
+export declare const shouldAutoExecuteGqlQuery: (method: GqlQueryMethod) => method is "QUERY";
 export declare const extractExpiresInSeconds: (headers: HttpHeaders) => number | null;
 export type ShouldRetryRequestOptions = {
     retryCount: number;
@@ -33,17 +38,22 @@ export type QueryFeatureFlags = {
     shouldAutoExecuteMethod: boolean;
     shouldAutoExecute: boolean;
     hasRouteFunction: boolean;
+    onlyManualExecution?: boolean;
+    /** Human readable method name */
+    method: string;
 };
-export declare const getQueryFeatureUsage: <TArgs extends QueryArgs>(options: CreateQueryOptions<TArgs>) => QueryFeatureFlags;
-export declare const applyQueryFeatures: <TArgs extends QueryArgs>(options: CreateQueryOptions<TArgs>, context: QueryFeatureContext<TArgs>) => void;
-export declare const maybeExecute: <TArgs extends QueryArgs>(options: {
+export declare const getQueryFeatureUsage: <TArgs extends QueryArgs>(options: CreateQueryOptions<TArgs> | CreateGqlQueryOptions<TArgs>) => QueryFeatureFlags;
+export declare const applyQueryFeatures: <TArgs extends QueryArgs>(features: QueryFeature<TArgs>[], context: QueryFeatureContext<TArgs>) => void;
+export declare const maybeExecute: (options: {
     flags: QueryFeatureFlags;
-    execute: QueryExecute<TArgs>;
+    execute: InternalQueryExecute<any>;
 }) => void;
 export type CreateQueryObjectOptions<TArgs extends QueryArgs> = {
     state: QueryState<TArgs>;
-    execute: QueryExecute<TArgs>;
-    createSnapshot: () => QuerySnapshot<TArgs>;
-    destroy: () => void;
+    deps: QueryDependencies;
+    execute: InternalQueryExecute<TArgs>;
 };
 export declare const createQueryObject: <TArgs extends QueryArgs>(options: CreateQueryObjectOptions<TArgs>) => Query<TArgs>;
+export declare const normalizeQueryRepositoryKey: (key: Signal<QueryKeyOrNone>) => Signal<string>;
+export declare const shouldCacheQuery: (method: QueryMethod) => method is "GET" | "HEAD" | "OPTIONS";
+export declare const buildQueryCacheKey: (route: string, args: RequestArgs<QueryArgs> | undefined) => string;

package/lib/experimental/{query.d.ts → http/query.d.ts}

@@ -23,22 +23,46 @@ export type CreateQueryOptions<TArgs extends QueryArgs> = {
     queryConfig: QueryConfig;
 };
 export type QueryBase<TArgs extends QueryArgs> = {
+    /** The arguments of the last execution of the query. Will be `null` if the query has never been executed */
     args: Signal<RequestArgs<TArgs> | null>;
+    /**
+     * The latest response of the query. Will be `null` if the query has never been executed.
+     * Responses are cached until a new response is received.
+     * If a response is present but the next execution of the query fails, the response will be set to `null` again.
+     */
     response: Signal<ResponseType<TArgs> | null>;
+    /** The latest Angular HTTP client native http event that occurred during the last execution of the query. Will be `null` if no event occurred. */
     latestHttpEvent: Signal<HttpEvent<ResponseType<TArgs>> | null>;
+    /** The loading state of the query. Will be `null` if the query currently isn't loading. */
     loading: Signal<HttpRequestLoadingState | null>;
+    /** The error that occurred during the last execution of the query. Will be `null` if no error occurred. */
     error: Signal<HttpErrorResponse | null>;
+    /** The time the query was last executed at. Will be `null` if the query has never been executed. */
     lastTimeExecutedAt: Signal<number | null>;
-    id: Signal<string | false>;
+    /** The id of the query */
+    id: Signal<string>;
 };
+/** A snapshot of a query state at a specific point in time */
 export type QuerySnapshot<TArgs extends QueryArgs> = QueryBase<TArgs> & {
+    /** This signal is `true` until the latest execution of the query has completed in any way (success, error, or cancellation) */
     isAlive: Signal<boolean>;
 };
 export type AnyQuerySnapshot = QuerySnapshot<any>;
 export type AnyQuery = Query<any>;
+export type QuerySubtle<TArgs extends QueryArgs> = {
+    /** Destroys the query and cleans up all resources. The query should not be used after this method is called. */
+    destroy: () => void;
+    /** Manually sets the response of the query. This will not trigger a new execution of the query. */
+    setResponse: (response: ResponseType<TArgs>) => void;
+};
 export type Query<TArgs extends QueryArgs> = QueryBase<TArgs> & {
+    /** Executes the query */
     execute: QueryExecute<TArgs>;
+    /** Creates an immutable snapshot of the current query state */
     createSnapshot: () => QuerySnapshot<TArgs>;
-    destroy: () => void;
+    /** Resets the query state to its initial state */
+    reset: () => void;
+    /** Advanced query features. **WARNING!** Incorrectly using these features will likely **BREAK** your application. You have been warned! */
+    subtle: QuerySubtle<TArgs>;
 };
 export declare const createQuery: <TArgs extends QueryArgs>(options: CreateQueryOptions<TArgs>) => Query<TArgs>;

package/lib/experimental/{secure-query-creator.d.ts → http/secure-query-creator.d.ts}

@@ -1,4 +1,4 @@
-import { AnyBearerAuthProviderConfig } from './bearer-auth-provider-config';
+import { AnyBearerAuthProviderConfig } from '../auth/bearer-auth-provider-config';
 import { QueryArgs } from './query';
 import { CreateQueryCreatorOptions, InternalCreateQueryCreatorOptions, QueryCreator } from './query-creator';
 export type InternalSecureCreateQueryCreatorOptions = InternalCreateQueryCreatorOptions & {

package/lib/experimental/{secure-query-execute.d.ts → http/secure-query-execute.d.ts}

@@ -1,7 +1,7 @@
 import { QueryArgs } from './query';
-import { CreateQueryExecuteOptions, QueryExecute } from './query-execute';
+import { CreateQueryExecuteOptions, InternalQueryExecute } from './query-execute';
 import { InternalSecureCreateQueryCreatorOptions } from './secure-query-creator';
 export type CreateSecureQueryExecuteOptions<TArgs extends QueryArgs> = Omit<CreateQueryExecuteOptions<TArgs>, 'creatorInternals'> & {
     creatorInternals: InternalSecureCreateQueryCreatorOptions;
 };
-export declare const createSecureExecuteFn: <TArgs extends QueryArgs>(options: CreateSecureQueryExecuteOptions<TArgs>) => QueryExecute<TArgs>;
+export declare const createSecureExecuteFn: <TArgs extends QueryArgs>(options: CreateSecureQueryExecuteOptions<TArgs>) => InternalQueryExecute<TArgs>;

package/lib/experimental/index.d.ts

@@ -1,22 +1,4 @@
-export * from './bearer-auth-provider';
-export * from './bearer-auth-provider-config';
-export * from './http-request';
-export * from './paged-query';
-export * from './query';
-export * from './query-client';
-export * from './query-client-config';
-export * from './query-creator';
-export * from './query-creator-templates';
-export * from './query-dependencies';
-export * from './query-errors';
-export * from './query-execute';
-export * from './query-execute-utils';
-export * from './query-features';
-export * from './query-repository';
-export * from './query-snapshot';
-export * from './query-stack';
-export * from './query-state';
-export * from './query-utils';
-export * from './secure-query';
-export * from './secure-query-creator';
-export * from './secure-query-execute';
+export * from './auth';
+export * from './gql';
+export * from './http';
+export * from './ws';

package/lib/experimental/ws/index.d.ts

@@ -0,0 +1,2 @@
+export * from './web-socket-client';
+export * from './web-socket-client-config';

package/lib/experimental/ws/web-socket-client-config.d.ts

@@ -0,0 +1,14 @@
+import { InjectionToken } from '@angular/core';
+import { SocketMessageView, WebSocketClient } from './web-socket-client';
+export type CreateWebSocketClientConfig = {
+    /** A unique name for the client */
+    name: string;
+    /** The URL of the socket io server */
+    url: string;
+};
+export type WebSocketClientRef<TMessageData extends SocketMessageView = SocketMessageView> = InjectionToken<WebSocketClient<TMessageData>>;
+export type WebSocketClientConfig = CreateWebSocketClientConfig & {
+    /** A generated token for dependency injection */
+    token: WebSocketClientRef;
+};
+export declare const createWebSocketClientConfig: (options: CreateWebSocketClientConfig) => WebSocketClientConfig;

package/lib/experimental/ws/web-socket-client.d.ts

@@ -0,0 +1,37 @@
+import { Signal, WritableSignal } from '@angular/core';
+import { WebSocketClientConfig } from './web-socket-client-config';
+/** A default socket io message view */
+export type SocketMessageView<TMessageData = unknown> = {
+    room: string;
+    event: string;
+    data: TMessageData;
+};
+export type WebSocketClientSubtle = {
+    /** Leave a socket io room */
+    leaveRoom: (room: string) => void;
+};
+export type WebSocketClient<TMessageData extends SocketMessageView> = {
+    /**
+     * Join a socket io room
+     * If a function is passed, it will be evaluated in a reactive signal context.
+     * If the function returns null, no room will be joined.
+     * If the function returns a string, the previous room will be left and the new room will be joined.
+     */
+    joinRoom: (room: string | (() => string | null)) => Signal<WebSocketRoom<TMessageData> | null>;
+    /** Whether the client is connected to the server */
+    isConnected: Signal<boolean>;
+    /** Advanced web socket features. **WARNING!** Incorrectly using these features will likely **BREAK** your application. You have been warned! */
+    subtle: WebSocketClientSubtle;
+};
+export type InternalWebSocketRoom<TMessageData extends SocketMessageView> = {
+    latestMessage: WritableSignal<TMessageData | null>;
+};
+export type WebSocketRoom<TMessageData extends SocketMessageView> = {
+    /** The latest message received in the room */
+    latestMessage: Signal<TMessageData | null>;
+};
+export declare const createWebSocketClient: <TMessageData extends SocketMessageView>(config: WebSocketClientConfig) => WebSocketClient<TMessageData>;
+export declare const provideWebSocketClient: (config: WebSocketClientConfig) => {
+    provide: import("./web-socket-client-config").WebSocketClientRef<SocketMessageView>;
+    useFactory: () => WebSocketClient<SocketMessageView<unknown>>;
+};

package/lib/experimental/ws/web-socket-errors.d.ts

@@ -0,0 +1,7 @@
+import { RuntimeError } from '@ethlete/core';
+export declare const enum WebSocketRuntimeErrorCode {
+    ROOM_NOT_JOINED = 1000,
+    MESSAGE_MALFORMED = 1001
+}
+export declare const roomNotJoined: (room: string) => RuntimeError<WebSocketRuntimeErrorCode.ROOM_NOT_JOINED>;
+export declare const messageMalformed: () => RuntimeError<WebSocketRuntimeErrorCode.MESSAGE_MALFORMED>;

package/lib/gql/gql.d.ts

@@ -1,6 +1,7 @@
-export declare const transformGql: (str: string) => (variables: Record<string, unknown> | null | undefined) => {
+export type TransformedGqlQuery = {
     query: string;
-    variables?: string;
+    variables?: Record<string, unknown>;
     operationName?: string;
 };
+export declare const transformGql: (str: string) => (variables: Record<string, unknown> | null | undefined) => TransformedGqlQuery;
 export declare const gql: (strings: TemplateStringsArray, ...values: string[]) => string;

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@ethlete/query",
-  "version": "5.23.0",
+  "version": "5.25.0",
+  "sideEffects": false,
   "peerDependencies": {
-    "@angular/common": "^18.1.0 || ^19.0.0",
-    "@angular/core": "^18.1.0 || ^19.0.0",
-    "@angular/forms": "^18.1.0 || ^19.0.0",
-    "@angular/router": "^18.1.0 || ^19.0.0",
+    "@angular/common": "19.1.4",
+    "@angular/core": "19.1.4",
+    "@angular/forms": "19.1.4",
+    "@angular/router": "19.1.4",
     "@ethlete/core": "^4.0.3",
     "@ethlete/types": "^1.6.2",
-    "rxjs": "^7.8.1"
+    "rxjs": "7.8.1",
+    "socket.io-client": "4.8.1"
   },
   "module": "fesm2022/ethlete-query.mjs",
   "typings": "index.d.ts",
@@ -21,7 +23,6 @@
       "default": "./fesm2022/ethlete-query.mjs"
     }
   },
-  "sideEffects": false,
   "dependencies": {
     "tslib": "^2.3.0"
   }

package/lib/experimental/paged-query.d.ts

@@ -1,77 +0,0 @@
-import { ContentfulGqlLikePaginated, DynLikePaginated, GgLikePaginated, NormalizedPagination, Paginated } from '@ethlete/types';
-import { Query, QueryArgs, RequestArgs, ResponseType } from './query';
-import { QueryCreator } from './query-creator';
-export declare const ethletePaginationAdapter: <T>(response: Paginated<T>) => NormalizedPagination<T>;
-export declare const ggLikePaginationAdapter: <T>(response: GgLikePaginated<T>) => NormalizedPagination<T>;
-export declare const dynLikePaginationAdapter: <T>(response: DynLikePaginated<T>) => NormalizedPagination<T>;
-export declare const contentfulGqlLikePaginationAdapter: <T>(response: ContentfulGqlLikePaginated<T>) => NormalizedPagination<T>;
-export type CreatePagedQueryOptions<TArgs extends QueryArgs> = {
-    /**
-     * The normalizer function that will be used to normalize the response to a format that the paged query can understand.
-     *
-     * There are some built-in normalizers that can be used:
-     * - `ethletePaginationAdapter`
-     * - `ggLikePaginationAdapter`
-     * - `dynLikePaginationAdapter`
-     * - `contentfulGqlLikePaginationAdapter`
-     */
-    responseNormalizer: (response: ResponseType<TArgs>) => NormalizedPagination<ResponseType<TArgs>>;
-    /**
-     * The query creator function that will be used to create the paged query.
-     */
-    queryCreator: QueryCreator<TArgs>;
-    /**
-     * The arguments to create the query.
-     * The current page will be passed as an argument.
-     * This function can be treated like a computed function. It reacts to signal changes.
-     * If a signal changes, the paged query will be reset to the initial page.
-     *
-     * @example (page) => ({ queryParams: { page, limit:20 } }),
-     */
-    args: (page: number) => RequestArgs<TArgs>;
-    /**
-     * The page to start this paged query from.
-     * @default 1
-     */
-    initialPage?: number;
-};
-export type PagedQueryResetOptions = {
-    /**
-     * The page to reset this paged query to.
-     * This will clear everything and start from this page.
-     * @default 1 // or the value passed in the `initialPage` option when creating the paged query.
-     */
-    initialPage?: number;
-};
-export type PagedQueryExecuteOptions<TArgs extends QueryArgs> = {
-    /**
-     * If provided, only the queries that match the condition will be executed.
-     * This will also execute the previous and next query to the one that matched the condition.
-     * If not provided, all queries will be executed.
-     *
-     * @example
-     * myPagedQuery.execute({ where: (item) => item.id === 4 });
-     */
-    where?: (item: ResponseType<TArgs>, index: number, array: ResponseType<TArgs>[]) => boolean;
-    /**
-     * If true, the cache will be used (if not expired) and the request will not be made.
-     * @default false
-     */
-    allowCache?: boolean;
-};
-export declare const createPagedQuery: <TArgs extends QueryArgs>(options: CreatePagedQueryOptions<TArgs>) => {
-    pagination: import("@angular/core").Signal<NormalizedPagination<ResponseType<TArgs>> | null>;
-    fetchPreviousPage: () => void;
-    fetchNextPage: () => void;
-    canFetchPreviousPage: import("@angular/core").Signal<boolean>;
-    canFetchNextPage: import("@angular/core").Signal<boolean>;
-    items: import("@angular/core").Signal<ResponseType<TArgs>[]>;
-    direction: import("@angular/core").Signal<"next" | "previous">;
-    loading: import("@angular/core").Signal<boolean>;
-    error: import("@angular/core").Signal<import("@angular/common/http").HttpErrorResponse | null>;
-    lastQuery: import("@angular/core").Signal<Query<TArgs> | null>;
-    isFirstLoad: import("@angular/core").Signal<boolean>;
-    queries: Query<TArgs>[];
-    reset: (resetOptions?: PagedQueryResetOptions) => void;
-    execute: (options?: PagedQueryExecuteOptions<TArgs>) => void;
-};

package/lib/experimental/query-client-config.d.ts

@@ -1,18 +0,0 @@
-import { HttpHeaders } from '@angular/common/http';
-import { InjectionToken } from '@angular/core';
-import { BuildQueryStringConfig } from '../request';
-import { QueryClient } from './query-client';
-import { ShouldRetryRequestFn } from './query-utils';
-export type CacheAdapterFn = (headers: HttpHeaders) => number | null;
-export type CreateQueryClientConfigOptions = {
-    baseUrl: string;
-    queryString?: BuildQueryStringConfig;
-    name: string;
-    cacheAdapter?: CacheAdapterFn;
-    retryFn?: ShouldRetryRequestFn;
-};
-export type QueryClientConfig = CreateQueryClientConfigOptions & {
-    token: QueryClientRef;
-};
-export type QueryClientRef = InjectionToken<QueryClient>;
-export declare const createQueryClientConfig: (options: CreateQueryClientConfigOptions) => QueryClientConfig;