feat(angular-query): created package for experimental persistence sup…

…port, and the withPersistQueryClient feature

packages/angular-persist-query-client-experimental/.attw.json

@@ -0,0 +1,3 @@
+{
+  "ignoreRules": ["cjs-resolves-to-esm", "no-resolution"]
+}

packages/angular-persist-query-client-experimental/config/api-extractor.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/build/index.d.ts",
+
+  "newlineKind": "lf",
+
+  "apiReport": {
+    "enabled": true
+  },
+
+  "docModel": {
+    "enabled": false
+  },
+
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/build/rollup.d.ts"
+  },
+
+  "tsdocMetadata": {
+    "enabled": false
+  }
+}

packages/angular-persist-query-client-experimental/eslint.config.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+import pluginJsdoc from 'eslint-plugin-jsdoc'
+import rootConfig from '../../eslint.config.js'
+
+export default [
+  ...rootConfig,
+  pluginJsdoc.configs['flat/recommended-typescript'],
+  {
+    rules: {
+      'cspell/spellchecker': [
+        'warn',
+        {
+          cspell: {
+            ignoreRegExpList: ['\\ɵ.+'],
+          },
+        },
+      ],
+      'jsdoc/require-hyphen-before-param-description': 1,
+      'jsdoc/sort-tags': 1,
+      'jsdoc/require-throws': 1,
+      'jsdoc/check-tag-names': [
+        'warn',
+        {
+          // Not compatible with Api Extractor @public
+          typed: false,
+        },
+      ],
+    },
+  },
+]

packages/angular-persist-query-client-experimental/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@tanstack/angular-query-persist-client-experimental",
+  "version": "5.61.1",
+  "description": "Angular bindings to work with persisters in TanStack/angular-query",
+  "author": "Omer Gronich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/query.git",
+    "directory": "packages/angular-query-persist-client-experimental"
+  },
+  "homepage": "https://tanstack.com/query",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "scripts": {
+    "clean": "rimraf ./build ./coverage",
+    "test:eslint": "eslint ./src",
+    "test:types": "pnpm run \"/^test:types:ts[0-9]{2}$/\"",
+    "test:types:ts50": "node ../../node_modules/typescript50/lib/tsc.js",
+    "test:types:ts51": "node ../../node_modules/typescript51/lib/tsc.js",
+    "test:types:ts52": "node ../../node_modules/typescript52/lib/tsc.js",
+    "test:types:ts53": "tsc",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm run test:lib --watch",
+    "test:build": "publint --strict && attw --pack",
+    "build": "pnpm build:tsup",
+    "build:tsup": "tsup"
+  },
+  "type": "module",
+  "types": "build/index.d.ts",
+  "module": "build/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./build/index.d.ts",
+        "default": "./build/index.js"
+      }
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "build",
+    "src",
+    "!src/__tests__"
+  ],
+  "dependencies": {
+    "@tanstack/query-persist-client-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@analogjs/vite-plugin-angular": "^1.6.4",
+    "@angular/compiler": "^17.3.12",
+    "@angular/core": "^17.3.12",
+    "@angular/platform-browser": "^17.3.12",
+    "@angular/platform-browser-dynamic": "^17.3.12",
+    "@microsoft/api-extractor": "^7.47.4",
+    "@tanstack/angular-query-experimental": "workspace:*",
+    "eslint-plugin-jsdoc": "^50.2.2",
+    "tsup": "8.0.2",
+    "typescript": "5.3.3"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=16.0.0",
+    "@angular/core": ">=16.0.0",
+    "@tanstack/angular-query-experimental": "workspace:*"
+  }
+}

packages/angular-persist-query-client-experimental/src/index.ts

@@ -0,0 +1,4 @@
+// Re-export core
+export * from '@tanstack/query-persist-client-core'
+
+export * from './with-persist-query-client'

packages/angular-persist-query-client-experimental/src/with-persist-query-client.ts

@@ -0,0 +1,94 @@
+import {
+  injectQueryClient,
+  provideIsRestoring,
+  queryFeature,
+} from '@tanstack/angular-query-experimental'
+import {
+  DestroyRef,
+  ENVIRONMENT_INITIALIZER,
+  PLATFORM_ID,
+  inject,
+  signal,
+} from '@angular/core'
+import { isPlatformBrowser } from '@angular/common'
+import {
+  persistQueryClientRestore,
+  persistQueryClientSubscribe,
+} from '@tanstack/query-persist-client-core'
+import type { PersistQueryClientOptions as PersistQueryClientOptionsCore } from '@tanstack/query-persist-client-core'
+import type { PersistQueryClientFeature } from '@tanstack/angular-query-experimental'
+
+type PersistQueryClientOptions = {
+  persistOptions: Omit<PersistQueryClientOptionsCore, 'queryClient'>
+  onSuccess?: () => Promise<unknown> | unknown
+}
+
+/**
+ * Enables persistence.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const localStoragePersister = createSyncStoragePersister({
+ *   storage: window.localStorage,
+ * })
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideTanStackQuery(
+ *       new QueryClient(),
+ *       withPersistQueryClient([
+ *         {
+ *           persistOptions: {
+ *             persister: localStoragePersister,
+ *           },
+ *           onSuccess: () => console.log('Restoration completed successfully.'),
+ *         },
+ *       ])
+ *     )
+ *   ]
+ * }
+ * ```
+ *
+ * @param persistQueryClientOptions - An array of objects containing persistOptions and an onSuccess callback which gets called when the restoration process is complete.
+ * @returns A set of providers for use with `provideTanStackQuery`.
+ * @public
+ */
+export function withPersistQueryClient(
+  persistQueryClientOptions: Array<PersistQueryClientOptions>,
+): PersistQueryClientFeature {
+  const isRestoring = signal(false)
+  const providers = [
+    provideIsRestoring(isRestoring.asReadonly()),
+    {
+      provide: ENVIRONMENT_INITIALIZER,
+      multi: true,
+      useValue: () => {
+        if (!isPlatformBrowser(inject(PLATFORM_ID))) return
+        const destroyRef = inject(DestroyRef)
+        const queryClient = injectQueryClient()
+
+        isRestoring.set(true)
+        const restorations = persistQueryClientOptions.map(
+          ({ onSuccess, persistOptions }) => {
+            const options = { queryClient, ...persistOptions }
+            return persistQueryClientRestore(options).then(async () => {
+              try {
+                if (onSuccess) {
+                  await onSuccess()
+                }
+              } finally {
+                const cleanup = persistQueryClientSubscribe(options)
+                destroyRef.onDestroy(cleanup)
+              }
+            })
+          },
+        )
+        Promise.all(restorations).finally(() => {
+          isRestoring.set(false)
+        })
+      },
+    },
+  ]
+  return queryFeature('PersistQueryClient', providers)
+}

packages/angular-persist-query-client-experimental/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "Bundler",
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noFallthroughCasesInSwitch": true,
+    "useDefineForClassFields": false,
+    "target": "ES2022",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src", "eslint.config.js", "tsup.config.js", "vite.config.ts"]
+}

packages/angular-persist-query-client-experimental/tsup.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  sourcemap: true,
+  clean: true,
+  format: ['esm'],
+  dts: true,
+  outDir: 'build',
+})

packages/angular-persist-query-client-experimental/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config'
+import packageJson from './package.json'
+
+export default defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './src',
+    watch: false,
+    environment: 'jsdom',
+    setupFiles: ['src/test-setup.ts'],
+    coverage: { enabled: true, provider: 'istanbul', include: ['src/**/*'] },
+    typecheck: { enabled: true },
+    globals: true,
+    restoreMocks: true,
+  },
+})

packages/angular-query-experimental/src/providers.ts

@@ -141,7 +141,7 @@ export interface QueryFeature<TFeatureKind extends QueryFeatureKind> {
  * @param providers -
  * @returns A Query feature.
  */
-function queryFeature<TFeatureKind extends QueryFeatureKind>(
+export function queryFeature<TFeatureKind extends QueryFeatureKind>(
   kind: TFeatureKind,
   providers: Array<Provider>,
 ): QueryFeature<TFeatureKind> {
@@ -156,6 +156,13 @@ function queryFeature<TFeatureKind extends QueryFeatureKind>(
  */
 export type DeveloperToolsFeature = QueryFeature<'DeveloperTools'>
 
+/**
+ * A type alias that represents a feature which enables persistence.
+ * The type is used to describe the return value of the `withPersistQueryClient` function.
+ * @public
+ */
+export type PersistQueryClientFeature = QueryFeature<'PersistQueryClient'>
+
 /**
  * Options for configuring the TanStack Query devtools.
  * @public
@@ -345,8 +352,8 @@ export function withDevtools(
  * @public
  * @see {@link provideTanStackQuery}
  */
-export type QueryFeatures = DeveloperToolsFeature // Union type of features but just one now
+export type QueryFeatures = DeveloperToolsFeature | PersistQueryClientFeature // Union type of features but just one now
 
-export const queryFeatures = ['DeveloperTools'] as const
+export const queryFeatures = ['DeveloperTools', 'PersistQueryClient'] as const
 
 export type QueryFeatureKind = (typeof queryFeatures)[number]