@tanstack/angular-db 0.0.1

package/README.md

@@ -0,0 +1,279 @@
+# @tanstack/angular-db
+
+Angular hooks for TanStack DB. See [TanStack/db](https://github.com/TanStack/db) for more details.
+
+Installation
+
+    npm install @tanstack/angular-db @tanstack/db
+
+Usage
+
+Basic Setup
+
+First, create a collection:
+
+    import { createCollection, localOnlyCollectionOptions } from "@tanstack/db"
+
+    interface Todo {
+      id: number
+      text: string
+      completed: boolean
+      projectID: number
+      created_at: Date
+    }
+
+    export const todosCollection = createCollection(
+      localOnlyCollectionOptions<Todo>({
+        getKey: (todo: Todo) => todo.id,
+        initialData: [
+          {
+            id: 1,
+            text: "Learn Angular",
+            completed: false,
+            projectID: 1,
+            created_at: new Date(),
+          },
+        ],
+      })
+    )
+
+Using injectLiveQuery in Components
+
+Direct Collection Usage
+
+The simplest way to use injectLiveQuery is to pass a collection directly:
+
+    import { Component } from "@angular/core"
+    import { injectLiveQuery } from "@tanstack/angular-db"
+    import { todosCollection } from "./collections/todos-collection"
+
+    @Component({
+      selector: "app-all-todos",
+      template: `
+        @if (allTodos.isReady()) {
+          <div>Total todos: {{ allTodos.data().length }}</div>
+          @for (todo of allTodos.data(); track todo.id) {
+            <div>{{ todo.text }}</div>
+          }
+        } @else {
+          <div>Loading todos...</div>
+        }
+      `,
+    })
+    export class AllTodosComponent {
+      // Direct collection usage - gets all items
+      allTodos = injectLiveQuery(todosCollection)
+    }
+
+Static Query Functions
+
+You can create filtered queries using a query function. Note: The query function is evaluated once and is not reactive to signal changes:
+
+    import { Component } from "@angular/core"
+    import { injectLiveQuery } from "@tanstack/angular-db"
+    import { eq } from "@tanstack/db"
+    import { todosCollection } from "./collections/todos-collection"
+
+    @Component({
+      selector: "app-todos",
+      template: `
+        @if (todoQuery.isReady()) {
+          @for (todo of todoQuery.data(); track todo.id) {
+            <div class="todo-item">
+              {{ todo.text }}
+              <button (click)="toggleTodo(todo.id)">
+                {{ todo.completed ? "Undo" : "Complete" }}
+              </button>
+            </div>
+          }
+        } @else {
+          <div>Loading todos...</div>
+        }
+      `,
+    })
+    export class TodosComponent {
+      // Static query - filters for incomplete todos
+      // This will not react to signal changes within the function
+      todoQuery = injectLiveQuery((q) =>
+        q
+          .from({ todo: todosCollection })
+          .where(({ todo }) => eq(todo.completed, false))
+      )
+
+      toggleTodo(id: number) {
+        todosCollection.utils.begin()
+        todosCollection.utils.write({
+          type: 'update',
+          key: id,
+          value: { completed: true }
+        })
+        todosCollection.utils.commit()
+      }
+    }
+
+Reactive Queries with Parameters
+
+For queries that need to react to component state changes, use the reactive parameters overload:
+
+    import { Component, signal } from "@angular/core"
+    import { injectLiveQuery } from "@tanstack/angular-db"
+    import { eq } from "@tanstack/db"
+    import { todosCollection } from "./collections/todos-collection"
+
+    @Component({
+      selector: "app-project-todos",
+      template: `
+        <select (change)="selectedProjectId.set(+$any($event).target.value)">
+          <option [value]="1">Project 1</option>
+          <option [value]="2">Project 2</option>
+          <option [value]="3">Project 3</option>
+        </select>
+
+        @if (todoQuery.isReady()) {
+          <div>Todos for project {{ selectedProjectId() }}:</div>
+          @for (todo of todoQuery.data(); track todo.id) {
+            <div class="todo-item">
+              {{ todo.text }}
+            </div>
+          }
+        } @else {
+          <div>Loading todos...</div>
+        }
+      `,
+    })
+    export class ProjectTodosComponent {
+      selectedProjectId = signal(1)
+
+      // Reactive query - automatically recreates when selectedProjectId changes
+      todoQuery = injectLiveQuery({
+        params: () => ({ projectID: this.selectedProjectId() }),
+        query: ({ params, q }) =>
+          q
+            .from({ todo: todosCollection })
+            .where(({ todo }) => eq(todo.completed, false))
+            .where(({ todo }) => eq(todo.projectID, params.projectID)),
+      })
+    }
+
+Advanced Configuration
+
+You can also pass a full configuration object:
+
+    import { Component } from "@angular/core"
+    import { injectLiveQuery } from "@tanstack/angular-db"
+    import { eq } from "@tanstack/db"
+    import { todosCollection } from "./collections/todos-collection"
+
+    @Component({
+      selector: "app-configured-todos",
+      template: `
+        @if (todoQuery.isReady()) {
+          @for (todo of todoQuery.data(); track todo.id) {
+            <div>{{ todo.text }}</div>
+          }
+        }
+      `,
+    })
+    export class ConfiguredTodosComponent {
+      todoQuery = injectLiveQuery({
+        query: (q) =>
+          q
+            .from({ todo: todosCollection })
+            .where(({ todo }) => eq(todo.completed, false))
+            .select(({ todo }) => ({
+              id: todo.id,
+              text: todo.text,
+            })),
+        startSync: true,
+        gcTime: 5000,
+      })
+    }
+
+Important Notes
+
+Reactivity Behavior
+
+- Direct collection: Automatically reactive to collection changes
+- Static query function: Query is built once and is not reactive to signals read within the function
+- Reactive parameters: Query rebuilds when any signal read in params() changes
+- Collection configuration: Static, not reactive to external signals
+
+Lifecycle Management
+
+- injectLiveQuery automatically handles subscription cleanup when the component is destroyed
+- Each call to injectLiveQuery creates a new collection instance (no caching/reuse)
+- Collections are started immediately and will sync according to their configuration
+
+Template Usage
+
+Use Angular's new control flow syntax for best performance:
+
+    @if (query.isReady()) {
+      @for (item of query.data(); track item.id) {
+        <div>{{ item.text }}</div>
+      }
+    } @else if (query.isError()) {
+      <div>Error loading data</div>
+    } @else {
+      <div>Loading...</div>
+    }
+
+API
+
+injectLiveQuery()
+
+Angular injection function for TanStack DB live queries. Must be called within an injection context (e.g., component constructor, inject(), or field initializer).
+
+Overloads
+
+    // Direct collection - reactive to collection changes
+    function injectLiveQuery<TResult, TKey, TUtils>(
+      collection: Collection<TResult, TKey, TUtils>
+    ): LiveQueryResult<TResult>
+
+    // Static query function - NOT reactive to signals within function
+    function injectLiveQuery<TContext>(
+      queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>
+    ): LiveQueryResult<TContext>
+
+    // Reactive query with parameters - recreates when params() signals change
+    function injectLiveQuery<TContext, TParams>(options: {
+      params: () => TParams
+      query: (args: {
+        params: TParams
+        q: InitialQueryBuilder
+      }) => QueryBuilder<TContext>
+    }): LiveQueryResult<TContext>
+
+    // Collection configuration - static configuration
+    function injectLiveQuery<TContext>(
+      config: LiveQueryCollectionConfig<TContext>
+    ): LiveQueryResult<TContext>
+
+Returns
+
+An object with Angular signals:
+
+- data: Signal<Array<T>> - Array of query results, automatically updates
+- state: Signal<Map<Key, T>> - Map of results by key, automatically updates
+- collection: Signal<Collection> - The underlying collection instance
+- status: Signal<CollectionStatus> - Current status ('idle' | 'loading' | 'ready' | 'error' | 'cleaned-up')
+- isLoading: Signal<boolean> - true when status is 'loading' or 'initialCommit'
+- isReady: Signal<boolean> - true when status is 'ready'
+- isIdle: Signal<boolean> - true when status is 'idle'
+- isError: Signal<boolean> - true when status is 'error'
+- isCleanedUp: Signal<boolean> - true when status is 'cleaned-up'
+
+Parameters
+
+- collection - Existing collection to observe directly
+- queryFn - Function that builds a static query using the query builder
+- options.params - Reactive function that returns parameters; triggers query rebuild when accessed signals change
+- options.query - Function that builds a query using parameters and query builder
+- config - Configuration object for creating a live query collection
+
+Requirements
+
+- Angular 16+ (requires signals support)
+- Must be called within an Angular injection context
+- Automatically handles cleanup when the injector is destroyed

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@tanstack/angular-db",
+  "description": "Angular integration for @tanstack/db",
+  "version": "0.0.1",
+  "author": "Ethan McDaniel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/db.git",
+    "directory": "packages/angular-db"
+  },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "optimistic",
+    "angular",
+    "typescript"
+  ],
+  "packageManager": "pnpm@10.6.3",
+  "dependencies": {
+    "@tanstack/db": "workspace:*"
+  },
+  "devDependencies": {
+    "@angular/common": "^19.0.0",
+    "@angular/core": "^19.0.0",
+    "@angular/platform-browser-dynamic": "^19.0.0",
+    "@vitest/coverage-istanbul": "^3.0.9",
+    "rxjs": "^7.8.0",
+    "zone.js": "^0.14.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "peerDependencies": {
+    "@angular/core": ">=16.0.0",
+    "rxjs": ">=6.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "npx vitest --run",
+    "lint": "eslint . --fix"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "dist/esm/index.d.ts"
+}

package/src/index.ts

@@ -0,0 +1,194 @@
+import {
+  DestroyRef,
+  assertInInjectionContext,
+  computed,
+  effect,
+  inject,
+  signal,
+} from "@angular/core"
+import { createLiveQueryCollection } from "@tanstack/db"
+import type {
+  ChangeMessage,
+  Collection,
+  CollectionStatus,
+  Context,
+  GetResult,
+  InitialQueryBuilder,
+  LiveQueryCollectionConfig,
+  QueryBuilder,
+} from "@tanstack/db"
+import type { Signal } from "@angular/core"
+
+/**
+ * The result of calling `injectLiveQuery`.
+ * Contains reactive signals for the query state and data.
+ */
+export interface InjectLiveQueryResult<
+  TResult = any,
+  TKey extends string | number = string | number,
+  TUtils extends Record<string, any> = Record<string, never>,
+> {
+  /** A signal containing the complete state map of results keyed by their ID */
+  state: Signal<Map<TKey, TResult>>
+  /** A signal containing the results as an array */
+  data: Signal<Array<TResult>>
+  /** A signal containing the underlying collection instance */
+  collection: Signal<Collection<TResult, TKey, TUtils>>
+  /** A signal containing the current status of the collection */
+  status: Signal<CollectionStatus>
+  /** A signal indicating whether the collection is currently loading */
+  isLoading: Signal<boolean>
+  /** A signal indicating whether the collection is ready */
+  isReady: Signal<boolean>
+  /** A signal indicating whether the collection is idle */
+  isIdle: Signal<boolean>
+  /** A signal indicating whether the collection has an error */
+  isError: Signal<boolean>
+  /** A signal indicating whether the collection has been cleaned up */
+  isCleanedUp: Signal<boolean>
+}
+
+export function injectLiveQuery<
+  TContext extends Context,
+  TParams extends any,
+>(options: {
+  params: () => TParams
+  query: (args: {
+    params: TParams
+    q: InitialQueryBuilder
+  }) => QueryBuilder<TContext>
+}): InjectLiveQueryResult<GetResult<TContext>>
+export function injectLiveQuery<TContext extends Context>(
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>
+): InjectLiveQueryResult<GetResult<TContext>>
+export function injectLiveQuery<TContext extends Context>(
+  config: LiveQueryCollectionConfig<TContext>
+): InjectLiveQueryResult<GetResult<TContext>>
+export function injectLiveQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils>
+): InjectLiveQueryResult<TResult, TKey, TUtils>
+export function injectLiveQuery(opts: any) {
+  assertInInjectionContext(injectLiveQuery)
+  const destroyRef = inject(DestroyRef)
+
+  const collection = computed(() => {
+    // Check if it's an existing collection
+    const isExistingCollection =
+      opts &&
+      typeof opts === `object` &&
+      typeof opts.subscribeChanges === `function` &&
+      typeof opts.startSyncImmediate === `function` &&
+      typeof opts.id === `string`
+
+    if (isExistingCollection) {
+      return opts
+    }
+
+    if (typeof opts === `function`) {
+      return createLiveQueryCollection({
+        query: opts,
+        startSync: true,
+        gcTime: 0,
+      })
+    }
+
+    // Check if it's reactive query options
+    const isReactiveQueryOptions =
+      opts &&
+      typeof opts === `object` &&
+      typeof opts.query === `function` &&
+      typeof opts.params === `function`
+
+    if (isReactiveQueryOptions) {
+      const { params, query } = opts
+      const currentParams = params()
+      return createLiveQueryCollection({
+        query: (q) => query({ params: currentParams, q }),
+        startSync: true,
+        gcTime: 0,
+      })
+    }
+
+    // Handle LiveQueryCollectionConfig objects
+    if (opts && typeof opts === `object` && typeof opts.query === `function`) {
+      return createLiveQueryCollection(opts)
+    }
+
+    throw new Error(`Invalid options provided to injectLiveQuery`)
+  })
+
+  const state = signal(new Map<string | number, any>())
+  const data = signal<Array<any>>([])
+  const status = signal<CollectionStatus>(`idle`)
+
+  const syncDataFromCollection = (
+    currentCollection: Collection<any, any, any>
+  ) => {
+    const newState = new Map(currentCollection.entries())
+    const newData = Array.from(currentCollection.values())
+
+    state.set(newState)
+    data.set(newData)
+    status.set(currentCollection.status)
+  }
+
+  let unsub: (() => void) | null = null
+  const cleanup = () => {
+    unsub?.()
+    unsub = null
+  }
+
+  effect((onCleanup) => {
+    const currentCollection = collection()
+
+    if (!currentCollection) {
+      return
+    }
+
+    cleanup()
+
+    // Initialize immediately with current state
+    syncDataFromCollection(currentCollection)
+
+    // Start sync if idle
+    if (currentCollection.status === `idle`) {
+      currentCollection.startSyncImmediate()
+      // Update status after starting sync
+      status.set(currentCollection.status)
+    }
+
+    // Subscribe to changes
+    unsub = currentCollection.subscribeChanges(
+      (_: Array<ChangeMessage<any>>) => {
+        syncDataFromCollection(currentCollection)
+      }
+    )
+
+    // Handle ready state
+    currentCollection.onFirstReady(() => {
+      status.set(currentCollection.status)
+    })
+
+    onCleanup(cleanup)
+  })
+
+  destroyRef.onDestroy(cleanup)
+
+  return {
+    state,
+    data,
+    collection,
+    status,
+    isLoading: computed(
+      () => status() === `loading` || status() === `initialCommit`
+    ),
+    isReady: computed(() => status() === `ready`),
+    isIdle: computed(() => status() === `idle`),
+    isError: computed(() => status() === `error`),
+    isCleanedUp: computed(() => status() === `cleaned-up`),
+  }
+}