or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application.mdauthentication.mderror-handling.mdindex.mdrest-transport.mdservices.mdsocketio-transport.md
tile.json

tessl/npm-feathersjs--client

A comprehensive client-side library for FeathersJS applications that consolidates REST and WebSocket transport methods with authentication, real-time synchronization, and unified service communication

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@feathersjs/client@5.0.x

To install, run

npx @tessl/cli install tessl/npm-feathersjs--client@5.0.0

index.mddocs/

FeathersJS Client

FeathersJS Client is a comprehensive client-side library that consolidates multiple transport methods including REST clients (supporting jQuery, Request, and Superagent) and WebSocket connections (supporting Socket.io and Primus). It provides a unified API for real-time data synchronization, authentication, and service communication across different transport protocols, enabling developers to build modern web applications with flexible client-server communication.

Package Information

  • Package Name: @feathersjs/client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @feathersjs/client

Core Imports

import feathers, { Application, FeathersService } from "@feathersjs/client";
import { authentication, rest, socketio, errors } from "@feathersjs/client";

For CommonJS:

const feathers = require("@feathersjs/client");
const { authentication, rest, socketio, errors } = require("@feathersjs/client");

Basic Usage

import feathers from "@feathersjs/client";
import { authentication, rest } from "@feathersjs/client";

// Create application instance
const app = feathers();

// Configure authentication
app.configure(authentication());

// Configure REST transport
app.configure(rest("http://localhost:3030").fetch(fetch));

// Use services
const userService = app.service("users");
const users = await userService.find();

// Authenticate
await app.authenticate({
  strategy: "local",
  email: "user@example.com",
  password: "password"
});

Architecture

FeathersJS Client is built around several key components:

  • Core Application: Factory function creating application instances with service management, hooks, and configuration
  • Transport Layer: Pluggable transport adapters for REST (fetch, axios, superagent) and WebSocket (Socket.io) communication
  • Authentication: JWT-based authentication with automatic token management and header population
  • Service Interface: Unified CRUD operations (find, get, create, update, patch, remove) across all transports
  • Real-time Events: Event-driven architecture for real-time data synchronization over WebSockets
  • Error Handling: Comprehensive HTTP-based error classes with consistent error formatting

Capabilities

Application Factory

Core application factory function and application management functionality for creating and configuring FeathersJS client instances.

function feathers<T = any, S = any>(): Application<T, S>;

interface Application<T = any, S = any> {
  version: string;
  services: Services;
  settings: Settings;
  mixins: ServiceMixin[];
  _isSetup: boolean;
  get<L extends keyof Settings>(name: L): Settings[L];
  set<L extends keyof Settings>(name: L, value: Settings[L]): this;
  configure(callback: (app: Application) => void): this;
  use<L extends keyof S>(path: L, service: ServiceInterface | Application, options?: ServiceOptions): this;
  unuse<L extends keyof S>(path: L): Promise<FeathersService>;
  service<L extends keyof S>(path: L): FeathersService<T>;
  defaultService(location: string): ServiceInterface;
  setup(server?: any): Promise<Application>;
  teardown(server?: any): Promise<Application>;
  hooks(map: ApplicationHookOptions): this;
}

Application Management

Service Interface

Unified CRUD service interface providing standardized methods for data operations across all transport layers.

interface FeathersService<T = any, D = Partial<T>, P extends Params = Params> {
  find(params?: P): Promise<Paginated<T> | T[]>;
  get(id: Id, params?: P): Promise<T>;
  create(data: D, params?: P): Promise<T>;
  update(id: NullableId, data: D, params?: P): Promise<T | T[]>;
  patch(id: NullableId, data: Partial<D>, params?: P): Promise<T | T[]>;
  remove(id: NullableId, params?: P): Promise<T | T[]>;
}

type Id = number | string;
type NullableId = Id | null;

interface Params<Q = Query> {
  query?: Q;
  provider?: string;
  user?: any;
  authenticated?: boolean;
  headers?: { [key: string]: any };
}

Service Operations

Authentication Client

JWT-based authentication with automatic token management, storage, and header population for secure API communication.

function authentication(options?: Partial<AuthenticationClientOptions>): (app: Application) => void;

interface AuthenticationClientOptions {
  header: string;
  scheme: string;
  storageKey: string;
  locationKey: string;
  locationErrorKey: string;
  jwtStrategy: string;
  path: string;
  storage: Storage;
}

// Methods added to Application
interface AuthenticatedApplication {
  authenticate(data?: AuthenticationRequest, params?: Params): Promise<AuthenticationResult>;
  reAuthenticate(force?: boolean, strategy?: string, params?: Params): Promise<AuthenticationResult>;
  logout(): Promise<AuthenticationResult | null>;
  authentication: AuthenticationClient;
}

Authentication

REST Client Transport

HTTP-based transport supporting multiple HTTP clients (fetch, axios, superagent) for traditional REST API communication.

function rest(baseURL?: string): {
  fetch(connection: any, options?: any): TransportConnection;
  axios(connection: any, options?: any): TransportConnection;
  superagent(connection: any, options?: any): TransportConnection;
};

interface RestClientParams extends Params {
  connection?: any;
}

REST Transport

Socket.IO Transport

Real-time WebSocket transport using Socket.io for live data synchronization and event-driven communication.

function socketio(socket: Socket, options?: any): TransportConnection;

interface SocketService<T = any, D = Partial<T>, P extends Params = Params> extends FeathersService<T, D, P> {
  on(event: string, listener: Function): this;
  off(event: string, listener?: Function): this;
  emit(event: string, ...args: any[]): this;
  addListener(event: string, listener: Function): this;
  removeListener(event: string, listener: Function): this;
  removeAllListeners(event?: string): this;
}

Socket.IO Transport

Error Handling

Comprehensive HTTP-based error classes providing consistent error handling across all transport methods and operations.

namespace errors {
  class FeathersError extends Error {
    name: string;
    message: string;
    code: number;
    className: string;
    data?: any;
    errors?: any;
  }

  // 4xx Client Errors
  class BadRequest extends FeathersError {}
  class NotAuthenticated extends FeathersError {}
  class Forbidden extends FeathersError {}
  class NotFound extends FeathersError {}
  class MethodNotAllowed extends FeathersError {}
  class Timeout extends FeathersError {}
  class Conflict extends FeathersError {}
  class Unprocessable extends FeathersError {}

  // 5xx Server Errors
  class GeneralError extends FeathersError {}
  class NotImplemented extends FeathersError {}
  class BadGateway extends FeathersError {}
  class Unavailable extends FeathersError {}

  function convert(error: any): Error;
}

Error Handling

Type Definitions

interface Settings {
  [key: string]: any;
}

interface Services {
  [path: string]: FeathersService;
}

interface ServiceOptions {
  methods?: string[];
  events?: string[];
  multi?: boolean | string[];
  paginate?: false | { default?: number; max?: number };
}

interface Query {
  [key: string]: any;
  $limit?: number;
  $skip?: number;
  $sort?: { [key: string]: 1 | -1 };
  $select?: string[];
  $populate?: any;
}

interface Paginated<T> {
  total: number;
  limit: number;
  skip: number;
  data: T[];
}

interface HookContext<A = Application, S = any> {
  app: A;
  service: S;
  path: string;
  method: string;
  type: HookType;
  params: Params;
  id?: Id;
  data?: any;
  result?: any;
  error?: any;
}

type HookType = "before" | "after" | "error" | "around";
type HookFunction<A = Application, S = any> = (context: HookContext<A, S>) => Promise<HookContext | void> | HookContext | void;
type AroundHookFunction<A = Application, S = any> = (context: HookContext<A, S>, next: NextFunction) => Promise<void>;
type NextFunction = () => Promise<void>;
type ServiceMixin = (service: any, location: string, options: ServiceOptions) => void;

interface ApplicationHookOptions<A = Application> {
  before?: {
    all?: HookFunction<A>[];
    find?: HookFunction<A>[];
    get?: HookFunction<A>[];
    create?: HookFunction<A>[];
    update?: HookFunction<A>[];
    patch?: HookFunction<A>[];
    remove?: HookFunction<A>[];
    [key: string]: HookFunction<A>[];
  };
  after?: {
    all?: HookFunction<A>[];
    find?: HookFunction<A>[];
    get?: HookFunction<A>[];
    create?: HookFunction<A>[];
    update?: HookFunction<A>[];
    patch?: HookFunction<A>[];
    remove?: HookFunction<A>[];
    [key: string]: HookFunction<A>[];
  };
  error?: {
    all?: HookFunction<A>[];
    find?: HookFunction<A>[];
    get?: HookFunction<A>[];
    create?: HookFunction<A>[];
    update?: HookFunction<A>[];
    patch?: HookFunction<A>[];
    remove?: HookFunction<A>[];
    [key: string]: HookFunction<A>[];
  };
  around?: {
    all?: AroundHookFunction<A>[];
    find?: AroundHookFunction<A>[];
    get?: AroundHookFunction<A>[];
    create?: AroundHookFunction<A>[];
    update?: AroundHookFunction<A>[];
    patch?: AroundHookFunction<A>[];
    remove?: AroundHookFunction<A>[];
    [key: string]: AroundHookFunction<A>[];
  };
}

interface TransportConnection<Services = any> {
  (app: Application): void;
}

interface ServiceInterface<Result = any, Data = Partial<Result>, ServiceParams extends Params = Params> {
  find?(params?: ServiceParams): Promise<Result | Result[]>;
  get?(id: Id, params?: ServiceParams): Promise<Result>;
  create?(data: Data, params?: ServiceParams): Promise<Result>;
  create?(data: Data[], params?: ServiceParams): Promise<Result[]>;
  update?(id: NullableId, data: Data, params?: ServiceParams): Promise<Result | Result[]>;
  patch?(id: NullableId, data: Partial<Data>, params?: ServiceParams): Promise<Result | Result[]>;
  remove?(id: NullableId, params?: ServiceParams): Promise<Result | Result[]>;
  setup?(app: Application, path: string): Promise<void>;
  teardown?(app: Application, path: string): Promise<void>;
}