{"id":49182,"library":"rest-client-sdk","title":"Rest Client JS SDK","description":"A JavaScript SDK generator that avoids custom API client implementations by letting you define entity mappings, attributes, and relations declaratively. Version 7.2.3 is current; the project has a slow release cadence with occasional minor bumps. Integrates token management (OAuth refresh), UnitOfWork for batch operations, and storage adapters (localforage, AsyncStorage). Ships TypeScript definitions. Differentiates from generic clients (Axios, Fetch) by providing a metadata-driven ORM-like layer over REST endpoints.","status":"active","version":"7.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/mapado/rest-client-js-sdk","tags":["javascript","Rest","SDK","API","typescript"],"install":[{"cmd":"npm install rest-client-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add rest-client-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add rest-client-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Default storage for token persistence in browser/Node; optional if custom storage is provided.","package":"localforage","optional":true},{"reason":"Default storage for token persistence in React Native; optional if custom storage is provided.","package":"@react-native-async-storage/async-storage","optional":true}],"imports":[{"note":"Package is ESM-only since v7. Use default import for the SDK factory.","wrong":"const RestClientSdk = require('rest-client-sdk')","symbol":"RestClientSdk","correct":"import RestClientSdk from 'rest-client-sdk'"},{"note":"Mapping is a named export, not a default one.","wrong":"import Mapping from 'rest-client-sdk/Mapping'","symbol":"Mapping","correct":"import { Mapping } from 'rest-client-sdk'"},{"note":"TokenStorage is exported from the main package, not a subpath.","wrong":"import { TokenStorage } from 'rest-client-sdk/TokenStorage'","symbol":"TokenStorage","correct":"import { TokenStorage } from 'rest-client-sdk'"},{"note":"ClassMetadata is a named export. The package does not export defaults per class.","wrong":"import classMetadata from 'rest-client-sdk'","symbol":"ClassMetadata","correct":"import { ClassMetadata } from 'rest-client-sdk'"},{"note":"Attribute is exported from the main index.","wrong":"import { Attribute } from 'rest-client-sdk/Attribute'","symbol":"Attribute","correct":"import { Attribute } from 'rest-client-sdk'"},{"note":"Relation is a named export. Its static properties like ONE_TO_MANY are accessed via Relation.ONE_TO_MANY.","wrong":"import Relation from 'rest-client-sdk'","symbol":"Relation","correct":"import { Relation } from 'rest-client-sdk'"}],"quickstart":{"code":"import RestClientSdk from 'rest-client-sdk';\nimport { Mapping, ClassMetadata, Attribute, Relation, TokenStorage } from 'rest-client-sdk';\n\nconst mapping = new Mapping('/api');\nconst productMeta = new ClassMetadata('products', 'products');\nproductMeta.setAttributeList([\n  new Attribute('@id', 'id', 'string', true),\n  new Attribute('name', 'name', 'string', false),\n]);\nproductMeta.setRelationList([\n  new Relation(Relation.ONE_TO_MANY, 'categories', 'categories', 'categories'),\n]);\n\nconst categoryMeta = new ClassMetadata('categories', 'categories');\ncategoryMeta.setAttributeList([\n  new Attribute('@id', 'id', 'string', true),\n  new Attribute('name', 'name', 'string', false),\n]);\n\nmapping.setMapping([productMeta, categoryMeta]);\n\nconst config = {\n  path: 'api.example.com',\n  scheme: 'https',\n  port: 443,\n  segment: '/v1',\n  authorizationType: 'Bearer',\n  useDefaultParameters: true,\n  unitOfWorkEnabled: true,\n};\n\nconst tokenStorage = new TokenStorage({\n  async generateToken() {\n    return { access_token: 'tok' };\n  },\n  async refreshToken() {\n    return { access_token: 'newtok' };\n  },\n}, globalThis.localStorage);\n\nconst client = new RestClientSdk(mapping, config, tokenStorage);\n\nclient.getList('products').then(products => console.log(products));","lang":"typescript","description":"Creates a mapping with Product and Category entities, configures token storage via a custom generator and localStorage, then initializes the SDK client and fetches a product list."},"warnings":[{"fix":"Switch to import syntax. If you must use require, use dynamic import() or stick to v6.x.","message":"Package converted to ESM-only in v7.0.0. CommonJS require() will not work.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Pass the API prefix to new Mapping('/prefix') and omit the second argument to ClassMetadata (or use it as the endpoint path).","message":"Mapping constructor argument changed: in v7, the prefix is passed to the Mapping constructor, not the pathRoot of each ClassMetadata. Older usage with pathRoot as second argument to ClassMetadata will break.","severity":"deprecated","affected_versions":">=7.0.0"},{"fix":"Wrap synchronous storage in a Promise-based adapter, e.g., use localforage or a custom wrapper.","message":"TokenStorage requires storage.getItem and storage.setItem to return Promises. Passing synchronous storage (like raw localStorage) will fail silently.","severity":"gotcha","affected_versions":"all"},{"fix":"Disable unitOfWork if you encounter 'Object could not be cloned' errors or use plain JSON-serializable entities.","message":"UnitOfWork uses a proxy that may not support all operations (e.g., Map/Set as entity properties). Serialization can fail for non-plain objects.","severity":"gotcha","affected_versions":"all"},{"fix":"Use Relation.ONE_TO_MANY, Relation.MANY_TO_ONE, or Relation.MANY_TO_MANY consistently.","message":"Relation constants changed from static strings to numeric enums internally. Relation.ONE_TO_MANY etc. are still available as static getters, but direct string comparison will fail.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure generateToken and refreshToken return { access_token: string }.","message":"Token generator must return an object with an access_token key. Refreshed token also must contain access_token. Failure to do so will cause 'Invalid token' errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'7.2.3':26 'adapt':51 'api':12,79 'asyncstorag':53 'attribut':21 'avoid':10 'axio':61 'batch':47 'bump':39 'cadenc':35 'client':2,13,60 'current':28 'custom':11 'declar':24 'defin':18 'definit':56 'differenti':57 'driven':68 'endpoint':75 'entiti':19 'fetch':62 'generat':8 'generic':59 'implement':14 'integr':40 'javascript':6,76 'js':3 'layer':72 'let':16 'like':71 'localforag':52 'manag':42 'map':20 'metadata':67 'metadata-driven':66 'minor':38 'oauth':43 'occasion':37 'oper':48 'orm':70 'orm-lik':69 'project':30 'provid':64 'refresh':44 'relat':23 'releas':34 'rest':1,74,77 'sdk':4,7,78 'ship':54 'slow':33 'storag':50 'token':41 'typescript':55,80 'unitofwork':45 'version':25","created_at":"2026-06-07T17:00:28.629268+00:00","updated_at":"2026-06-07T17:00:28.629268+00:00","problems":[{"fix":"Replace const RestClientSdk = require('rest-client-sdk') with import RestClientSdk from 'rest-client-sdk'.","cause":"Using CommonJS require() on ESM-only package (v7+).","error":"TypeError: rest_client_sdk_1.default is not a constructor"},{"fix":"Use import { Mapping } from 'rest-client-sdk'.","cause":"Importing from a subpath that does not exist in v7+; all exports are from the main index.","error":"Cannot find module 'rest-client-sdk/Mapping'"},{"fix":"Use import { TokenStorage } from 'rest-client-sdk'.","cause":"Importing TokenStorage as a default export, but it is a named export.","error":"TokenStorage is not a constructor"},{"fix":"Return { access_token: 'your-token' } from generateToken and refreshToken.","cause":"Token generator function returned an object without an access_token property.","error":"Invalid token: access_token missing"},{"fix":"Disable unitOfWork in config (unitOfWorkEnabled: false) or ensure all entity properties are plain JSON types.","cause":"UnitOfWork is enabled and entity contains non-serializable fields (e.g., Date, Map, Set).","error":"SerializationError: Object could not be cloned"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/mapado/rest-client-js-sdk#readme","github":"https://github.com/mapado/rest-client-js-sdk","docs":null,"changelog":null,"pypi":null,"npm":"rest-client-sdk","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}