@data-client/rest 0.16.4 → 0.16.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-client/rest",
-  "version": "0.16.4",
+  "version": "0.16.6",
   "description": "Quickly define typed REST resources and endpoints",
   "homepage": "https://dataclient.io/rest",
   "repository": {
@@ -84,6 +84,7 @@
   },
   "exports": {
     ".": {
+      "types": "./lib/index.d.ts",
       "module": "./lib/index.js",
       "import": "./node.mjs",
       "require": "./dist/index.js",
@@ -116,7 +117,7 @@
     "README.md"
   ],
   "scripts": {
-    "build:lib": "NODE_ENV=production BROWSERSLIST_ENV='2020' POLYFILL_TARGETS='chrome>88,safari>14' yarn g:babel --out-dir lib",
+    "build:lib": "NODE_ENV=production BROWSERSLIST_ENV='2020' POLYFILL_TARGETS='chrome>88,safari>14' yarn g:babel --out-dir lib && NODE_ENV=production BROWSERSLIST_ENV='2020' yarn g:rollup",
     "build:legacy:lib": "NODE_ENV=production BROWSERSLIST_ENV='2018' POLYFILL_TARGETS='chrome>80,safari>13,firefox>72' yarn g:babel --out-dir legacy",
     "build:js:node": "BROWSERSLIST_ENV=node12 yarn g:rollup",
     "build:js:browser": "BROWSERSLIST_ENV=legacy yarn g:rollup",
@@ -124,7 +125,7 @@
     "build:clean": "yarn g:clean ts4.0 ts4.1 index.d.ts next.d.ts",
     "build:legacy-types": "yarn g:downtypes lib ts4.0 --to=4.0 && yarn g:downtypes lib ts4.1 --to=4.1 && yarn g:copy --up 1 ./src-4.1-types/**/*.d.ts ./ts4.0/ && yarn g:copy --up 1 ./src-4.1-types/**/*.d.ts ./ts4.1 && yarn g:copy --up 1 ./src-4.0-types/**/*.d.ts ./ts4.0",
     "build": "run build:lib && run build:legacy:lib && run build:bundle",
-    "dev": "run build:lib -w",
+    "dev": "NODE_ENV=production BROWSERSLIST_ENV='2020' POLYFILL_TARGETS='chrome>88,safari>14' yarn g:babel --out-dir lib -w",
     "prepare": "run build:lib",
     "prepack": "run prepare && run build:bundle && run build:legacy:lib",
     "tsc:ci": "yarn g:tsc --project tsconfig.test.json",
@@ -135,7 +136,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime": "^7.20.0",
-    "@data-client/endpoint": "^0.16.3",
+    "@data-client/endpoint": "^0.16.6",
     "path-to-regexp": "^8.1.0"
   },
   "devDependencies": {

package/src/RestEndpoint.js

@@ -12,6 +12,16 @@ import {
   isPojo,
 } from './RestHelpers.js';
 
+const textLikeRe =
+  /\btext\b|\bxml\b|\bhtml\b|\bjavascript\b|\bcss\b|\bcsv\b|\burlencoded\b/;
+
+function jsonResponse(response) {
+  return response.json().catch(error => {
+    error.status = 400;
+    throw error;
+  });
+}
+
 /** Simplifies endpoint definitions that follow REST patterns
  *
  * @see https://dataclient.io/rest/api/RestEndpoint
@@ -54,6 +64,21 @@ export default class RestEndpoint extends Endpoint {
       (!('body' in this) || this.body !== undefined) &&
       !['GET', 'DELETE'].includes(this.method);
 
+    /* istanbul ignore else */
+    if (process.env.NODE_ENV !== 'production') {
+      if (
+        this.content &&
+        this.content !== 'json' &&
+        this.schema != null &&
+        typeof this.schema !== 'string' &&
+        typeof this.schema !== 'undefined'
+      ) {
+        console.error(
+          `content '${this.content}' is incompatible with schema. Binary/text responses cannot be normalized. Use schema: undefined.`,
+        );
+      }
+    }
+
     Object.defineProperty(this, 'name', {
       get() {
         // using 'in' to ensure inheritance lookup
@@ -143,50 +168,76 @@ export default class RestEndpoint extends Endpoint {
   }
 
   parseResponse(response) {
-    // this should not have any content to read
     if (response.status === 204) return Promise.resolve(null);
-    if (!response.headers.get('content-type')?.includes('json')) {
-      return response.text().then(text => {
-        // string or 'not set' schema, are valid
-        // when overriding process they might handle other cases, so we don't want to block on our logic
+
+    if (this.content) {
+      /* istanbul ignore else */
+      if (process.env.NODE_ENV !== 'production') {
+        if (
+          this.content !== 'json' &&
+          this.schema != null &&
+          typeof this.schema !== 'string' &&
+          typeof this.schema !== 'undefined'
+        ) {
+          const error = new NetworkError(response);
+          error.status = 400;
+          error.message = `content '${this.content}' is incompatible with schema. Binary/text responses cannot be normalized. Use schema: undefined.`;
+          throw error;
+        }
+      }
+      if (this.content === 'stream') return Promise.resolve(response.body);
+      return this.content === 'json' ?
+          jsonResponse(response)
+        : response[this.content]();
+    }
+
+    const contentType = response.headers.get('content-type');
+    if (contentType?.includes('json')) return jsonResponse(response);
+
+    const isBinary = contentType && !textLikeRe.test(contentType);
+
+    if (
+      typeof this.schema === 'string' ||
+      typeof this.schema === 'undefined' ||
+      this.schema === null ||
+      this.process !== RestEndpoint.prototype.process
+    )
+      return isBinary ? response.blob() : response.text();
+
+    if (isBinary) {
+      const error = new NetworkError(response);
+      error.status = 400;
+      error.message = `Unexpected binary content-type for schema ${this.schema}`;
+      /* istanbul ignore else */
+      if (process.env.NODE_ENV !== 'production') {
+        error.message = `Unexpected binary content-type "${contentType}" for schema ${this.schema}. Binary responses cannot be normalized. Use schema: undefined or set content: 'blob'.`;
+      }
+      throw error;
+    }
+
+    return response.text().then(text => {
+      const error = new NetworkError(response);
+      error.status = 404;
+      error.message = `Unexpected text response for schema ${this.schema}`;
+      /* istanbul ignore else */
+      if (process.env.NODE_ENV !== 'production') {
         if (
-          ['string', 'undefined'].includes(typeof this.schema) ||
-          this.schema === null ||
-          this.process !== RestEndpoint.prototype.process
-        )
-          return text;
-
-        const error = new NetworkError(response);
-        error.status = 404;
-        error.message = `Unexpected text response for schema ${this.schema}`;
-        // custom dev-only messages for more detailed cause
-        /* istanbul ignore else */
-        if (process.env.NODE_ENV !== 'production') {
-          if (
-            !(
-              response.headers.get('content-type')?.includes('html') ||
-              text.startsWith('<!doctype html>')
-            )
-          ) {
-            if (tryParse(text) !== undefined) {
-              error.message = `"content-type" header does not include "json", but JSON response found.
+          !(contentType?.includes('html') || text.startsWith('<!doctype html>'))
+        ) {
+          if (tryParse(text) !== undefined) {
+            error.message = `"content-type" header does not include "json", but JSON response found.
 See https://www.rfc-editor.org/rfc/rfc4627 for information on JSON responses
 
 Using parsed JSON.
 If text content was expected see https://dataclient.io/rest/api/RestEndpoint#parseResponse`;
-            }
-          } else {
-            error.message = `Unexpected html response for schema ${this.schema}
+          }
+        } else {
+          error.message = `Unexpected html response for schema ${this.schema}
 This likely means no API endpoint was configured for this request, resulting in an HTML fallback.
 
 Response (first 300 characters): ${text.substring(0, 300)}`;
-          }
         }
-        throw error;
-      });
-    }
-    return response.json().catch(error => {
-      error.status = 400;
+      }
       throw error;
     });
   }

package/src/RestEndpointTypes.ts

@@ -1,4 +1,5 @@
 import type {
+  Denormalize,
   EndpointExtraOptions,
   EndpointInstanceInterface,
   Schema,
@@ -14,6 +15,23 @@ import {
 import { PathArgs, SoftPathArgs } from './pathTypes.js';
 import { EndpointUpdateFunction } from './RestEndpointTypeHelp.js';
 
+export type ContentType = 'json' | 'blob' | 'text' | 'arrayBuffer' | 'stream';
+
+interface ContentTypeMap {
+  blob: Blob;
+  text: string;
+  arrayBuffer: ArrayBuffer;
+  stream: ReadableStream<Uint8Array>;
+  json: any;
+}
+
+type ContentReturnType<C extends ContentType> = ContentTypeMap[C];
+
+type ContentSchemaGuard<O> =
+  O extends { content: 'blob' | 'text' | 'arrayBuffer' | 'stream' } ?
+    { schema?: undefined }
+  : {};
+
 export interface RestInstanceBase<
   F extends FetchFunction = FetchFunction,
   S extends Schema | undefined = any,
@@ -48,6 +66,8 @@ export interface RestInstanceBase<
   readonly signal: AbortSignal | undefined;
   /** @see https://dataclient.io/rest/api/RestEndpoint#paginationField */
   readonly paginationField?: string;
+  /** @see https://dataclient.io/rest/api/RestEndpoint#content */
+  readonly content?: ContentType;
 
   /* fetch lifecycles */
   /* before-fetch */
@@ -105,7 +125,8 @@ export interface RestInstanceBase<
     this: E,
     options: Readonly<
       RestEndpointExtendOptions<ExtendOptions, E, F> & ExtendOptions
-    >,
+    > &
+      ContentSchemaGuard<ExtendOptions>,
   ): RestExtendedEndpoint<ExtendOptions, E>;
 }
 
@@ -155,10 +176,10 @@ export interface RestInstance<
   push: AddEndpoint<
     F,
     ExtractCollection<S>['push'],
-    Exclude<O, 'body' | 'method'> & {
+    Omit<O, 'body' | 'method'> & {
       body:
-        | OptionsToAdderBodyArgument<O>
-        | OptionsToAdderBodyArgument<O>[]
+        | OptionsToAdderBodyArgument<O, ExtractCollection<S>['push']>
+        | OptionsToAdderBodyArgument<O, ExtractCollection<S>['push']>[]
         | FormData;
     }
   >;
@@ -168,10 +189,10 @@ export interface RestInstance<
   unshift: AddEndpoint<
     F,
     ExtractCollection<S>['unshift'],
-    Exclude<O, 'body' | 'method'> & {
+    Omit<O, 'body' | 'method'> & {
       body:
-        | OptionsToAdderBodyArgument<O>
-        | OptionsToAdderBodyArgument<O>[]
+        | OptionsToAdderBodyArgument<O, ExtractCollection<S>['unshift']>
+        | OptionsToAdderBodyArgument<O, ExtractCollection<S>['unshift']>[]
         | FormData;
     }
   >;
@@ -181,8 +202,13 @@ export interface RestInstance<
   assign: AddEndpoint<
     F,
     ExtractCollection<S>,
-    Exclude<O, 'body' | 'method'> & {
-      body: Record<string, OptionsToAdderBodyArgument<O>> | FormData;
+    Omit<O, 'body' | 'method'> & {
+      body:
+        | Record<
+            string,
+            OptionsToAdderBodyArgument<O, ExtractCollection<S>['assign']>
+          >
+        | FormData;
     }
   >;
   /** Remove item(s) (PATCH) from collection
@@ -191,10 +217,12 @@ export interface RestInstance<
   remove: RemoveEndpoint<
     F,
     ExtractCollection<S>['remove'],
-    Exclude<O, 'body' | 'method'> & {
+    Omit<O, 'body' | 'method'> & {
       body:
-        | OptionsToAdderBodyArgument<O>
-        | OptionsToAdderBodyArgument<O>[]
+        | Partial<OptionsToAdderBodyArgument<O, ExtractCollection<S>['remove']>>
+        | Partial<
+            OptionsToAdderBodyArgument<O, ExtractCollection<S>['remove']>
+          >[]
         | FormData;
     }
   >;
@@ -206,7 +234,9 @@ export interface RestInstance<
     ExtractCollection<S>['move'],
     {
       path: 'movePath' extends keyof O ? O['movePath'] & string : O['path'];
-      body: OptionsToAdderBodyArgument<O> | FormData;
+      body:
+        | Partial<OptionsToAdderBodyArgument<O, ExtractCollection<S>['move']>>
+        | FormData;
     }
   >;
 }
@@ -248,7 +278,10 @@ type OptionsToRestEndpoint<
         Extract<O['sideEffect'], boolean | undefined>
       : 'method' extends keyof O ? MethodToSide<O['method']>
       : E['sideEffect'],
-      O['process'] extends {} ? ReturnType<O['process']> : ResolveType<F>,
+      O['process'] extends {} ? ReturnType<O['process']>
+      : 'content' extends keyof O ?
+        ContentReturnType<O['content'] & ContentType>
+      : ResolveType<F>,
       {
         path: Exclude<O['path'], undefined>;
         body: 'body' extends keyof O ? O['body'] : E['body'];
@@ -276,7 +309,10 @@ type OptionsToRestEndpoint<
         Extract<O['sideEffect'], boolean | undefined>
       : 'method' extends keyof O ? MethodToSide<O['method']>
       : E['sideEffect'],
-      O['process'] extends {} ? ReturnType<O['process']> : ResolveType<F>,
+      O['process'] extends {} ? ReturnType<O['process']>
+      : 'content' extends keyof O ?
+        ContentReturnType<O['content'] & ContentType>
+      : ResolveType<F>,
       {
         path: E['path'];
         body: O['body'];
@@ -302,7 +338,10 @@ type OptionsToRestEndpoint<
         Extract<O['sideEffect'], boolean | undefined>
       : 'method' extends keyof O ? MethodToSide<O['method']>
       : E['sideEffect'],
-      O['process'] extends {} ? ReturnType<O['process']> : ResolveType<F>,
+      O['process'] extends {} ? ReturnType<O['process']>
+      : 'content' extends keyof O ?
+        ContentReturnType<O['content'] & ContentType>
+      : ResolveType<F>,
       {
         path: E['path'];
         body: E['body'];
@@ -343,9 +382,10 @@ export type RestExtendedEndpoint<
       { paginationField: E['getPage']['paginationField'] }
     : unknown),
   RestInstance<
-    (
-      ...args: Parameters<E>
-    ) => O['process'] extends {} ? Promise<ReturnType<O['process']>>
+    (...args: Parameters<E>) => O['process'] extends {} ?
+      Promise<ReturnType<O['process']>>
+    : 'content' extends keyof O ?
+      Promise<ContentReturnType<O['content'] & ContentType>>
     : ReturnType<E>,
     'schema' extends keyof O ? O['schema'] : E['schema'],
     'sideEffect' extends keyof O ? Extract<O['sideEffect'], boolean | undefined>
@@ -373,6 +413,8 @@ export interface PartialRestGenerics {
   readonly paginationField?: string;
   /** @see https://dataclient.io/rest/api/RestEndpoint#process */
   process?(value: any, ...args: any): any;
+  /** @see https://dataclient.io/rest/api/RestEndpoint#content */
+  readonly content?: ContentType;
 }
 /** Generic types when constructing a RestEndpoint
  *
@@ -532,8 +574,8 @@ type InferRestMethodWhenOmitted<O extends RestGenerics> =
 type MethodArgForBodyInference<O extends RestGenerics> =
   'method' extends keyof O ? O['method'] : InferRestMethodWhenOmitted<O>;
 
-type OptionsToAdderBodyArgument<O extends { body?: any }> =
-  'body' extends keyof O ? O['body'] : any;
+type OptionsToAdderBodyArgument<O extends { body?: any }, EntitySchema = any> =
+  'body' extends keyof O ? O['body'] : Partial<Denormalize<EntitySchema>>;
 
 export interface RestEndpointOptions<
   F extends FetchFunction = FetchFunction,
@@ -560,6 +602,8 @@ export interface RestEndpointOptions<
    * @see https://dataclient.io/rest/api/RestEndpoint#parseResponse
    */
   parseResponse?(response: Response): Promise<any>;
+  /** @see https://dataclient.io/rest/api/RestEndpoint#content */
+  content?: ContentType;
 
   sideEffect?: boolean | undefined;
   name?: string;
@@ -586,6 +630,8 @@ export type RestEndpointConstructorOptions<O extends RestGenerics = any> =
       : SoftPathArgs<O['path']>,
       OptionsToBodyArgument<O, MethodArgForBodyInference<O>>,
       O['process'] extends {} ? ReturnType<O['process']>
+      : 'content' extends keyof O ?
+        ContentReturnType<O['content'] & ContentType>
       : any /*Denormalize<O['schema']>*/
     >,
     O['schema']
@@ -607,6 +653,7 @@ export interface RestEndpoint<
     : PathArgs<O['path']>,
     OptionsToBodyArgument<O, MethodArgForBodyInference<O>>,
     O['process'] extends {} ? ReturnType<O['process']>
+    : 'content' extends keyof O ? ContentReturnType<O['content'] & ContentType>
     : any /*Denormalize<O['schema']>*/
   >,
   'schema' extends keyof O ? O['schema'] : undefined,
@@ -628,7 +675,9 @@ export interface RestEndpointConstructor {
     sideEffect,
     name,
     ...options
-  }: RestEndpointConstructorOptions<O> & Readonly<O>): RestEndpoint<O>;
+  }: RestEndpointConstructorOptions<O> &
+    Readonly<O> &
+    ContentSchemaGuard<O>): RestEndpoint<O>;
   readonly prototype: RestInstanceBase;
 }
 

package/src/RestHelpers.ts

@@ -1,12 +1,11 @@
-// Namespace import avoids webpack's per-export CJS validation, which fails in
-// StackBlitz WebContainers. Named imports (`import { compile }`) trigger
-// `importExportsPresence` checks that break there. `import *` defers property
-// access to runtime. No tree-shaking loss: CJS modules are included whole
-// regardless of import style, and webpack 5 traces static access on namespaces.
-import type { PathFunction, Token, ParamData } from 'path-to-regexp';
-import * as pathToRegexpModule from 'path-to-regexp';
-const { compile, parse, pathToRegexp } = pathToRegexpModule;
-
+import {
+  compile,
+  PathFunction,
+  parse,
+  pathToRegexp,
+  Token,
+  ParamData,
+} from './pathToRegexp.js';
 import { ShortenPath } from './pathTypes.js';
 
 const urlBaseCache: Record<string, PathFunction<object>> = Object.create(null);