client-rest-framework

WORK IN PROGRESS

Table of Contents

• Introduction
• Installation
• Quick Start
• API
• Serializers
• Repository
• Repository Types

Introduction

client-rest-framework is a TypeScript library that lets you build repositories to manage entities with just a few lines of code—using patterns familiar to Django REST framework. It ships APIs, serializers, and repositories that make it straightforward to interact with RESTful back‑ends in a structured, type‑safe way.

Features

• Powerful, flexible two‑directional serializers for custom serialisation and deserialisation logic.
• Support for custom serializers so you can tailor mapping to your exact needs.
• Strongly‑typed entities derived from serializers, providing compile‑time safety and avoiding common errors.
• Built‑in support for an Axios‑based HTTP client, with hooks for headers and error handling.
• Object‑oriented design inspired by Django REST framework.
• Composable repositories—include only the operations you need (read‑only, write‑only, or your own mix).

Installation

npm install client-rest-framework

Quick Start

import { api, serializers, repositories, pagination } from "client-rest-framework";

// 1. HTTP client
class HTTPClient extends api.AxiosHTTPClient {
  getExtraHeaders() {
    return { Authorization: `Bearer ${access}` };
  }

  // Called when the backend responds with 401
  onUnauthenticate = () => {
    logout();
  };
}

// 2. Base API class
class API<T> extends api.RESTAPI<T> {
  options = { appendSlash: true };
  pagination = new pagination.PageNumberPagination<T>({ pageSize: PAGE_SIZE });
  client = new HTTPClient({ baseURL: BASE_URL });
}

// 3. Endpoint‑specific API
class PublicUserAPI extends API<PublicUserDTO> {
  pagination = new pagination.PageNumberPagination<PublicUserDTO>();
  url = "/api/users";
}

// 4. Serializer
class PublicUserSerializer extends serializers.ModelSerializer<PublicUserDTO> {
  id           = new serializers.NumberField();
  username     = new serializers.StringField();
  email        = new serializers.StringField();
  display_name = new serializers.StringField();
  date_joined  = new serializers.DateField();
}

// 5. Repository
class PublicUserRepository extends repositories.ReadOnlyRepository {
  api        = new PublicUserAPI();
  serializer = new PublicUserSerializer();
}

// 6. Usage
const users = new PublicUserRepository();
const userList = await users.list();
const user = await users.get(1);

API

Create an API class by extending RESTAPI, injecting an HTTPClient, and setting the url field. The API class can then be passed to a repository to realise CRUD operations.

import { api, pagination } from "client-rest-framework";
import { PublicUserDTO } from "./types";

class HTTPClient extends api.AxiosHTTPClient {
  getExtraHeaders() {
    return { Authorization: `Bearer ${access}` };
  }

  onUnauthenticate = () => {
    logout();
  };
}

class API<T> extends api.RESTAPI<T> {
  client = new HTTPClient({ baseURL: BASE_URL });
}

class PublicUserAPI extends API<PublicUserDTO> {
  pagination = new pagination.PageNumberPagination<PublicUserDTO>();
  url = "/api/users";
}

API Pagination

Two pagination helpers are available:

// Returns [items: DTO[], { count: number }]
class NumberedAPI extends api.RESTAPI {
  pagination = new pagination.PageNumberPagination({
    pageSize: 50,
    pageSizeQueryParam: "page_size",
    pageQueryParam: "page",
  });
}

// Returns items untouched
class FlatAPI extends api.RESTAPI {
  pagination = new pagination.NoPagination();
}

Serializers

Serializers map data to and from your domain model.

import { serializers } from "client-rest-framework";
import { PublicUserDTO, RoleKey, UserStatusKey, CategoryKey } from "./types";

export class PublicUserSerializer extends serializers.ModelSerializer<PublicUserDTO> {
  id           = new serializers.NumberField({ readonly: true });
  username     = new serializers.StringField({ readonly: true });
  email        = new serializers.StringField({ readonly: true });
  display_name = new serializers.StringField({ readonly: true });
  date_joined  = new serializers.DateField({ readonly: true });

  notes      = new serializers.StringField({ many: true, optional: true });
  phone      = new serializers.StringField({ optional: true });
  roles      = new serializers.EnumField<RoleKey, false, true>({ many: true });
  status     = new serializers.EnumField<UserStatusKey>();
  categories = new serializers.EnumField<CategoryKey, false, true, true>({ many: true, optional: true });
}

Inferring Types

type Domain<T extends { fromDTO: (...a: never[]) => any }> = ReturnType<T["fromDTO"]>;
type Payload<T extends { toDTO: (...a: never[]) => any }> = Parameters<T["toDTO"]>[0];

export type PublicUser        = Domain<PublicUserSerializer>;
export type PublicUserPayload = Payload<PublicUserSerializer>;

Custom Serializers

Create bespoke mappings when you need defaults or complex structures:

export class TemplateSerializer<R extends boolean = false, M extends boolean = false>
  extends serializers.BaseSerializer<R, M> {

  fromDTO = (data: string | null) =>
    (typeof data === "string" ? data : DEFAULT_RESUME_TEMPLATE) as ResumeTemplateKey;

  toDTO = (data: ResumeTemplateKey) => data;
}

export interface ImageStruct {
  file2x : string;
  file  : string;
  thumb : string;
  thumb2x: string;
}

export class ImageSerializer<R extends boolean = false, M extends boolean = false>
  extends serializers.BaseSerializer<R, M> {

  private static EXT = ".webp";

  fromDTO = (filename: string): ImageStruct => {
    const id = filename.split(".")[0];
    return {
      file2x : `${id}_2x${ImageSerializer.EXT}`,
      file   : `${id}${ImageSerializer.EXT}`,
      thumb  : `${id}_t${ImageSerializer.EXT}`,
      thumb2x: `${id}_t2x${ImageSerializer.EXT}`,
    };
  };

  toDTO = (image: ImageStruct | string) =>
    typeof image === "string" ? image : image.file;
}

Nested Serializers

class ResumeMinimalSerializer<R extends boolean = false, M extends boolean = false>
  extends serializers.ModelSerializer<any, R, M> {
  id         = new serializers.StringField({ readonly: true });
  updated_at = new serializers.DateField({ readonly: true });
}

export class ApplicationSerializer<R extends boolean = false, M extends boolean = false>
  extends serializers.ModelSerializer<ApplicationDTO, R, M> {
  id       = new serializers.NumberField({ readonly: true });
  position = new serializers.StringField();
  company  = new serializers.StringField();
  resumes  = new ResumeMinimalSerializer({ readonly: true, many: true });
}

Repository

Define a repository by extending one of the provided classes and wiring in an api and a serializer.

Basic Usage

import { repositories } from "client-rest-framework";
import { PublicUserAPI } from "./api";
import { PublicUserSerializer } from "./serializers";

// Read‑only (get & list)
export class PublicUserRepository extends repositories.ReadOnlyRepository {
  api        = new PublicUserAPI();
  serializer = new PublicUserSerializer();
}

// Full CRUD
export class AdminUserRepository extends repositories.ModelRepository {
  api        = new PublicUserAPI();
  serializer = new PublicUserSerializer();
}

Using the Repository

const users = new PublicUserRepository();

// Get a user
const user = await users.get(1);

// List users (page 1)
const [list, { count }] = await users.list(1);

// Full CRUD example
const admin = new AdminUserRepository();
const created = await admin.create(data);
const updated = await admin.update(1, diff);
await admin.delete(1);

Query Parameters

const [articles] = await articlesRepository.list(1, {
  queryParams: {
    page_size : 20,
    author    : 42,
    rating_min: 5,
  },
});

Repository Types

Choose a predefined repository class—or compose your own—to control allowed operations.

| Repository | Methods | Typical Use | | ------------------------ | --------------------------------- | ------------------------------ | | ModelRepository | create, get, list, update, delete | Full admin control | | ReadOnlyRepository | get, list | Public APIs, documentation | | ListOnlyRepository | list | Dropdowns, catalogues, search | | CreateOnlyRepository | create | Logging, analytics, write‑only | | RetrieveOnlyRepository | get | Detail pages |

Custom Compositions

import { repositories } from "client-rest-framework";

class BulkCleanupRepository extends repositories.mixins.DestroyMixin(
  repositories.mixins.ListMixin(repositories.BaseRepository),
) {
  api        = new CleanupAPI();
  serializer = new ItemSerializer();
}

Important Notes and Limitations

• list() currently supports DRF PageNumberPagination only.
• The package is in early alpha—APIs may change.