angular

@spoosh/angular

Angular signals integration for Spoosh - injectRead, injectWrite, and injectPages.

Documentation · Requirements: TypeScript >= 5.0, Angular >= 16.0

Installation

npm install @spoosh/core @spoosh/angular

Usage

Setup

import { Spoosh } from "@spoosh/core";
import { create } from "@spoosh/angular";
import { cachePlugin } from "@spoosh/plugin-cache";

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
]);

export const { injectRead, injectWrite, injectPages } = create(spoosh);

injectRead

Fetch data with automatic caching and triggering using Angular signals.

@Component({
  template: `
    @if (users.loading()) {
      <div>Loading...</div>
    } @else if (users.error()) {
      <div>Error: {{ users.error()?.message }}</div>
    } @else {
      <ul>
        @for (user of users.data(); track user.id) {
          <li>{{ user.name }}</li>
        }
      </ul>
    }
  `,
})
export class UserListComponent {
  users = injectRead((api) => api("users").GET());
}

// With options
@Component({ ... })
export class UserListComponent {
  isReady = signal(false);

  // Recommended: Pass signal directly (shorter syntax)
  users = injectRead(
    (api) => api("users").GET({ query: { page: 1 } }),
    {
      staleTime: 10000,
      enabled: this.isReady,
    }
  );

  // With path parameters
  userId = signal(123);
  user = injectRead(
    (api) => api("users/:id").GET({ params: { id: this.userId() } }),
    { enabled: () => this.userId() !== null }
  );
}

injectWrite

Trigger mutations with loading and error states.

@Component({
  template: `
    <form (ngSubmit)="handleSubmit()">
      <input [(ngModel)]="title" />
      <button [disabled]="createUser.loading()">
        {{ createUser.loading() ? "Creating..." : "Create User" }}
      </button>
    </form>
  `,
})
export class CreateUserComponent {
  title = signal("");

  createUser = injectWrite((api) => api("users").POST());

  async handleSubmit() {
    const result = await this.createUser.trigger({
      body: { name: this.title() },
    });

    if (result.data) {
      // Success
    }
  }
}

// With path parameters
updateUser = injectWrite((api) => api("users/:id").PUT());

async updateUserName(userId: number, name: string) {
  await this.updateUser.trigger({
    params: { id: userId },
    body: { name },
  });
}

injectPages

Bidirectional paginated data fetching with infinite scroll support.

@Component({
  template: `
    @if (posts.canFetchPrev()) {
      <button (click)="posts.fetchPrev()" [disabled]="posts.fetchingPrev()">
        {{ posts.fetchingPrev() ? "Loading..." : "Load Previous" }}
      </button>
    }

    @for (post of posts.data(); track post.id) {
      <app-post-card [post]="post" />
    }

    @if (posts.canFetchNext()) {
      <button (click)="posts.fetchNext()" [disabled]="posts.fetchingNext()">
        {{ posts.fetchingNext() ? "Loading..." : "Load More" }}
      </button>
    }
  `,
})
export class PostListComponent {
  posts = injectPages((api) => api("posts").GET({ query: { page: 1 } }), {
    // Required: Check if next page exists
    canFetchNext: ({ lastPage }) => lastPage?.data?.meta.hasMore ?? false,

    // Required: Build request for next page
    nextPageRequest: ({ lastPage }) => ({
      query: { page: (lastPage?.data?.meta.page ?? 0) + 1 },
    }),

    // Required: Merge all pages into items
    merger: (pages) => pages.flatMap((p) => p.data?.items ?? []),

    // Optional: Check if previous page exists
    canFetchPrev: ({ firstPage }) => (firstPage?.data?.meta.page ?? 1) > 1,

    // Optional: Build request for previous page
    prevPageRequest: ({ firstPage }) => ({
      query: { page: (firstPage?.data?.meta.page ?? 2) - 1 },
    }),
  });
}

API Reference

injectRead(readFn, options?)

Option	Type	Default	Description
enabled	boolean | Signal<boolean> | () => boolean	true	Whether to fetch automatically
staleTime	number	-	Cache stale time (from plugin-cache)
retries	number	-	Retry attempts (from plugin-retry)
+ plugin options	-	-	Options from installed plugins

Returns:

Property	Type	Description
data	Signal<TData | undefined>	Response data
error	Signal<TError | undefined>	Error if request failed
loading	Signal<boolean>	True during initial load
fetching	Signal<boolean>	True during any fetch
meta	Signal<PluginResults>	Plugin metadata (e.g., transformedData)
trigger	() => Promise	Manually trigger fetch
abort	() => void	Abort current request

injectWrite(writeFn)

Returns:

Property	Type	Description
trigger	(options) => Promise	Execute the mutation
data	Signal<TData | undefined>	Response data
error	Signal<TError | undefined>	Error if request failed
loading	Signal<boolean>	True while mutation is in progress
meta	Signal<PluginResults>	Plugin metadata
input	TriggerOptions | undefined	Last trigger input
abort	() => void	Abort current request

injectPages(readFn, options)

Option	Type	Required	Description
merger	(pages) => TItem[]	Yes	Merge all pages into items
canFetchNext	(ctx) => boolean	No	Check if next page exists. Default: () => false
nextPageRequest	(ctx) => Partial<TRequest>	No	Build request for next page
canFetchPrev	(ctx) => boolean	No	Check if previous page exists
prevPageRequest	(ctx) => Partial<TRequest>	No	Build request for previous page
enabled	boolean | Signal<boolean> | () => boolean	No	Whether to fetch automatically

Context object passed to callbacks:

// For canFetchNext and nextPageRequest
type NextContext<TData, TRequest> = {
  lastPage: InfinitePage<TData> | undefined;
  pages: InfinitePage<TData>[];
  request: TRequest;
};

// For canFetchPrev and prevPageRequest
type PrevContext<TData, TRequest> = {
  firstPage: InfinitePage<TData> | undefined;
  pages: InfinitePage<TData>[];
  request: TRequest;
};

// Each page in the pages array
type InfinitePage<TData> = {
  status: "pending" | "loading" | "success" | "error" | "stale";
  data?: TData;
  error?: TError;
  meta?: TMeta;
  input?: { query?; params?; body? };
};

Returns:

Property	Type	Description
data	Signal<TItem[] | undefined>	Merged items from all pages
pages	Signal<InfinitePage<TData>[]>	Array of all pages with status, data, and meta
loading	Signal<boolean>	True during initial load
fetching	Signal<boolean>	True during any fetch
fetchingNext	Signal<boolean>	True while fetching next page
fetchingPrev	Signal<boolean>	True while fetching previous
canFetchNext	Signal<boolean>	Whether next page exists
canFetchPrev	Signal<boolean>	Whether previous page exists
fetchNext	() => Promise<void>	Fetch the next page
fetchPrev	() => Promise<void>	Fetch the previous page
trigger	(options?) => Promise<void>	Trigger fetch with optional new request options
abort	() => void	Abort current request
error	Signal<TError | undefined>	Error if request failed