@hkdigital/lib-core 0.4.55 → 0.4.57

package/dist/network/README.md

@@ -27,6 +27,85 @@ const result = await jsonRequest('https://api.example.com/users', {
 });
 ```
 
+### HTTP Methods
+
+Convenient methods for common HTTP operations:
+
+```javascript
+import { 
+  httpGet, 
+  httpPost, 
+  httpPut, 
+  httpPatch, 
+  httpDelete 
+} from '$lib/network/http.js';
+
+// GET request
+const response = await httpGet({ url: '/api/users' });
+const data = await response.text();
+
+// POST request with form data
+const formResponse = await httpPost({
+  url: '/api/users',
+  body: new FormData(form)
+});
+
+// PUT request with custom headers
+const putResponse = await httpPut({
+  url: '/api/users/123',
+  body: 'raw data',
+  headers: { 'Content-Type': 'text/plain' }
+});
+
+// PATCH request
+const patchResponse = await httpPatch({
+  url: '/api/users/123',
+  body: JSON.stringify({ status: 'active' }),
+  headers: { 'Content-Type': 'application/json' }
+});
+
+// DELETE request
+const deleteResponse = await httpDelete({ url: '/api/users/123' });
+```
+
+### JSON HTTP Methods
+
+Convenient methods for common JSON API operations:
+
+```javascript
+import { 
+  jsonGet, 
+  jsonPost, 
+  jsonPut, 
+  jsonPatch, 
+  jsonDelete 
+} from '$lib/network/http.js';
+
+// GET request for JSON data
+const users = await jsonGet({ url: '/api/users' });
+
+// POST request with JSON body
+const newUser = await jsonPost({
+  url: '/api/users',
+  body: JSON.stringify({ name: 'Jane', email: 'jane@example.com' })
+});
+
+// PUT request to update resource
+const updatedUser = await jsonPut({
+  url: '/api/users/123',
+  body: JSON.stringify({ name: 'Jane Smith' })
+});
+
+// PATCH request for partial updates
+const patchedUser = await jsonPatch({
+  url: '/api/users/123', 
+  body: JSON.stringify({ email: 'newemail@example.com' })
+});
+
+// DELETE request
+const result = await jsonDelete({ url: '/api/users/123' });
+```
+
 ### URL Utilities
 
 ```javascript
@@ -128,7 +207,9 @@ class CustomLoader extends NetworkLoader {
 
 ### HTTP (`$lib/network/http.js`)
 - `httpRequest()` - Make HTTP requests with configuration
-- `jsonRequest()` - Make JSON API requests  
+- `httpGet()`, `httpPost()`, `httpPut()`, `httpPatch()`, `httpDelete()` - Convenient HTTP methods
+- `jsonRequest()` - Make JSON API requests
+- `jsonGet()`, `jsonPost()`, `jsonPut()`, `jsonPatch()`, `jsonDelete()` - Convenient JSON HTTP methods
 - `toURL()` - Convert strings to URL objects with params
 - `setRequestHeaders()` - Set and merge request headers
 - `waitForAndCheckResponse()` - Handle responses with error checking

package/dist/network/http/json-request.d.ts

@@ -82,3 +82,121 @@ export function jsonGet(options: import("./typedef").JsonGetOptions): Promise<an
  * });
  */
 export function jsonPost(options: import("./typedef").JsonPostOptions): Promise<any>;
+/**
+ * Make a PUT request to fetch JSON encoded data
+ *
+ * This function performs a PUT request with JSON data and expects a JSON
+ * response from the server. It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonPutOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON PUT request
+ * try {
+ *   const updatedUser = {
+ *     name: "Jane Smith",
+ *     email: "jane@example.com"
+ *   };
+ *
+ *   const data = await jsonPut({
+ *     url: 'https://api.example.com/users/123',
+ *     body: JSON.stringify(updatedUser)
+ *   });
+ *
+ *   console.log('Updated user:', data);
+ * } catch (error) {
+ *   console.error('Failed to update user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON PUT with authentication and timeout
+ * const data = await jsonPut({
+ *   url: 'https://api.example.com/protected/resource/456',
+ *   body: JSON.stringify({ action: 'replace' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 5000
+ * });
+ */
+export function jsonPut(options: import("./typedef").JsonPutOptions): Promise<any>;
+/**
+ * Make a PATCH request to fetch JSON encoded data
+ *
+ * This function performs a PATCH request with JSON data and expects a JSON
+ * response from the server. It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonPatchOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON PATCH request
+ * try {
+ *   const partialUpdate = {
+ *     email: "newemail@example.com"
+ *   };
+ *
+ *   const data = await jsonPatch({
+ *     url: 'https://api.example.com/users/123',
+ *     body: JSON.stringify(partialUpdate)
+ *   });
+ *
+ *   console.log('Patched user:', data);
+ * } catch (error) {
+ *   console.error('Failed to patch user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON PATCH with authentication and timeout
+ * const data = await jsonPatch({
+ *   url: 'https://api.example.com/protected/resource/456',
+ *   body: JSON.stringify({ action: 'partial_update' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 5000
+ * });
+ */
+export function jsonPatch(options: import("./typedef").JsonPatchOptions): Promise<any>;
+/**
+ * Make a DELETE request to fetch JSON encoded data
+ *
+ * This function performs a DELETE request and expects a JSON response from the server.
+ * It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonDeleteOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON DELETE request
+ * try {
+ *   const data = await jsonDelete({
+ *     url: 'https://api.example.com/users/123'
+ *   });
+ *   console.log('User deleted:', data);
+ * } catch (error) {
+ *   console.error('Failed to delete user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON DELETE request with parameters and authentication
+ * const data = await jsonDelete({
+ *   url: 'https://api.example.com/posts/456',
+ *   urlSearchParams: new URLSearchParams({ force: 'true' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 3000
+ * });
+ */
+export function jsonDelete(options: import("./typedef").JsonDeleteOptions): Promise<any>;

package/dist/network/http/json-request.js

@@ -1,4 +1,4 @@
-import { METHOD_GET, METHOD_POST } from '../../constants/http/methods.js';
+import { METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE } from '../../constants/http/methods.js';
 
 import { APPLICATION_JSON } from '../../constants/mime/application.js';
 import { CONTENT_TYPE } from '../../constants/http/headers.js';
@@ -223,3 +223,323 @@ export async function jsonPost(options) {
 
   return parsedResponse;
 }
+
+/**
+ * Make a PUT request to fetch JSON encoded data
+ *
+ * This function performs a PUT request with JSON data and expects a JSON
+ * response from the server. It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonPutOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON PUT request
+ * try {
+ *   const updatedUser = {
+ *     name: "Jane Smith",
+ *     email: "jane@example.com"
+ *   };
+ *
+ *   const data = await jsonPut({
+ *     url: 'https://api.example.com/users/123',
+ *     body: JSON.stringify(updatedUser)
+ *   });
+ *
+ *   console.log('Updated user:', data);
+ * } catch (error) {
+ *   console.error('Failed to update user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON PUT with authentication and timeout
+ * const data = await jsonPut({
+ *   url: 'https://api.example.com/protected/resource/456',
+ *   body: JSON.stringify({ action: 'replace' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 5000
+ * });
+ */
+export async function jsonPut(options) {
+  // Extract specific parameters needed for this function
+  const {
+    url: rawUrl,
+    body,
+    urlSearchParams,
+    headers,
+    withCredentials,
+    ...otherOptions
+  } = options;
+
+  const url = toURL(rawUrl);
+
+  // Apply JSON-specific defaults and validation
+  expect.defined(body);
+
+  /** @type {Record<string, string>} */
+  const jsonHeaders = headers || {};
+  jsonHeaders[ACCEPT] = APPLICATION_JSON;
+  jsonHeaders[CONTENT_TYPE] = APPLICATION_JSON;
+
+  // Check if body is a string when using application/json
+  if (
+    jsonHeaders[CONTENT_TYPE] === APPLICATION_JSON &&
+    typeof body !== 'string'
+  ) {
+    throw new Error(
+      `Trying to send request with [content-type:${APPLICATION_JSON}], ` +
+        'but body is not a (JSON encoded) string.'
+    );
+  }
+
+  // Create request with all options
+  const responsePromise = httpRequest({
+    method: METHOD_PUT,
+    url,
+    body,
+    urlSearchParams,
+    headers: jsonHeaders,
+    withCredentials,
+    ...otherOptions // Pass through any other options
+  });
+
+  const response = await waitForAndCheckResponse(responsePromise, url);
+
+  let parsedResponse;
+
+  try {
+    //
+    // @note when security on the client side fails, an `opaque` response
+    //       is returned by the browser (empty body) -> parsing fails
+    //       (use CORS to fix this)
+    //
+    parsedResponse = await response.json();
+  } catch (e) {
+    throw new ResponseError(
+      `Failed to JSON decode server response from [${decodeURI(url.href)}]`,
+      {
+        cause: e
+      }
+    );
+  }
+
+  if (parsedResponse.error) {
+    //
+    // @note this is API specific, but it's quite logical
+    //
+    throw new ResponseError(
+      `Server returned response error message [${parsedResponse.error}]`
+    );
+  }
+
+  return parsedResponse;
+}
+
+/**
+ * Make a PATCH request to fetch JSON encoded data
+ *
+ * This function performs a PATCH request with JSON data and expects a JSON
+ * response from the server. It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonPatchOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON PATCH request
+ * try {
+ *   const partialUpdate = {
+ *     email: "newemail@example.com"
+ *   };
+ *
+ *   const data = await jsonPatch({
+ *     url: 'https://api.example.com/users/123',
+ *     body: JSON.stringify(partialUpdate)
+ *   });
+ *
+ *   console.log('Patched user:', data);
+ * } catch (error) {
+ *   console.error('Failed to patch user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON PATCH with authentication and timeout
+ * const data = await jsonPatch({
+ *   url: 'https://api.example.com/protected/resource/456',
+ *   body: JSON.stringify({ action: 'partial_update' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 5000
+ * });
+ */
+export async function jsonPatch(options) {
+  // Extract specific parameters needed for this function
+  const {
+    url: rawUrl,
+    body,
+    urlSearchParams,
+    headers,
+    withCredentials,
+    ...otherOptions
+  } = options;
+
+  const url = toURL(rawUrl);
+
+  // Apply JSON-specific defaults and validation
+  expect.defined(body);
+
+  /** @type {Record<string, string>} */
+  const jsonHeaders = headers || {};
+  jsonHeaders[ACCEPT] = APPLICATION_JSON;
+  jsonHeaders[CONTENT_TYPE] = APPLICATION_JSON;
+
+  // Check if body is a string when using application/json
+  if (
+    jsonHeaders[CONTENT_TYPE] === APPLICATION_JSON &&
+    typeof body !== 'string'
+  ) {
+    throw new Error(
+      `Trying to send request with [content-type:${APPLICATION_JSON}], ` +
+        'but body is not a (JSON encoded) string.'
+    );
+  }
+
+  // Create request with all options
+  const responsePromise = httpRequest({
+    method: METHOD_PATCH,
+    url,
+    body,
+    urlSearchParams,
+    headers: jsonHeaders,
+    withCredentials,
+    ...otherOptions // Pass through any other options
+  });
+
+  const response = await waitForAndCheckResponse(responsePromise, url);
+
+  let parsedResponse;
+
+  try {
+    //
+    // @note when security on the client side fails, an `opaque` response
+    //       is returned by the browser (empty body) -> parsing fails
+    //       (use CORS to fix this)
+    //
+    parsedResponse = await response.json();
+  } catch (e) {
+    throw new ResponseError(
+      `Failed to JSON decode server response from [${decodeURI(url.href)}]`,
+      {
+        cause: e
+      }
+    );
+  }
+
+  if (parsedResponse.error) {
+    //
+    // @note this is API specific, but it's quite logical
+    //
+    throw new ResponseError(
+      `Server returned response error message [${parsedResponse.error}]`
+    );
+  }
+
+  return parsedResponse;
+}
+
+/**
+ * Make a DELETE request to fetch JSON encoded data
+ *
+ * This function performs a DELETE request and expects a JSON response from the server.
+ * It handles common error cases and parses the JSON response.
+ *
+ * @param {import('./typedef').JsonDeleteOptions} options
+ *   Request configuration options
+ *
+ * @returns {Promise<any>} Parsed JSON data
+ *
+ * @example
+ * // Basic JSON DELETE request
+ * try {
+ *   const data = await jsonDelete({
+ *     url: 'https://api.example.com/users/123'
+ *   });
+ *   console.log('User deleted:', data);
+ * } catch (error) {
+ *   console.error('Failed to delete user:', error.message);
+ * }
+ *
+ * @example
+ * // JSON DELETE request with parameters and authentication
+ * const data = await jsonDelete({
+ *   url: 'https://api.example.com/posts/456',
+ *   urlSearchParams: new URLSearchParams({ force: 'true' }),
+ *   headers: {
+ *     'authorization': 'Bearer ' + token
+ *   },
+ *   withCredentials: true,
+ *   timeoutMs: 3000
+ * });
+ */
+export async function jsonDelete(options) {
+  // Extract specific parameters needed for this function
+  const {
+    url: rawUrl,
+    urlSearchParams,
+    headers,
+    withCredentials,
+    ...otherOptions
+  } = options;
+
+  const url = toURL(rawUrl);
+
+  // Apply JSON-specific defaults
+  const jsonHeaders = headers || {};
+  jsonHeaders[ACCEPT] = APPLICATION_JSON;
+
+  // Create request with all options
+  const responsePromise = httpRequest({
+    method: METHOD_DELETE,
+    url,
+    urlSearchParams,
+    headers: jsonHeaders,
+    withCredentials,
+    ...otherOptions // Pass through any other options
+  });
+
+  const response = await waitForAndCheckResponse(responsePromise, url);
+
+  let parsedResponse;
+
+  try {
+    //
+    // @note when security on the client side fails, an `opaque` response
+    //       is returned by the browser (empty body) -> parsing fails
+    //       (use CORS to fix this)
+    //
+    parsedResponse = await response.json();
+  } catch (e) {
+    throw new ResponseError(
+      `Failed to JSON decode server response from [${decodeURI(url.href)}]`,
+      {
+        cause: e
+      }
+    );
+  }
+
+  if (parsedResponse.error) {
+    throw new ResponseError(
+      `Server returned response error message [${parsedResponse.error}]`
+    );
+  }
+
+  return parsedResponse;
+}

package/dist/network/http/typedef.d.ts

@@ -163,6 +163,152 @@ export type JsonPostOptions = {
      */
     cacheEnabled?: boolean | undefined;
 };
+export type JsonPutOptions = {
+    /**
+     * URL string or URL object for the request
+     */
+    url: string | URL;
+    /**
+     * Request body (will be sent as JSON)
+     */
+    body: any;
+    /**
+     * Parameters to add to the URL
+     */
+    urlSearchParams?: Object | URLSearchParams | undefined;
+    /**
+     * HTTP headers as name-value pairs
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Whether to include credentials
+     */
+    withCredentials?: boolean | undefined;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Handler for abort/timeout control
+     */
+    requestHandler?: RequestHandler | undefined;
+    /**
+     * CORS mode ('cors', 'no-cors', 'same-origin')
+     */
+    mode?: string | undefined;
+    /**
+     * Cache mode ('default', 'no-cache', etc.)
+     */
+    cache?: string | undefined;
+    /**
+     * Redirect mode ('follow', 'error', 'manual')
+     */
+    redirect?: string | undefined;
+    /**
+     * Referrer policy
+     */
+    referrerPolicy?: string | undefined;
+    /**
+     * Enable or disabled automatic caching
+     */
+    cacheEnabled?: boolean | undefined;
+};
+export type JsonPatchOptions = {
+    /**
+     * URL string or URL object for the request
+     */
+    url: string | URL;
+    /**
+     * Request body (will be sent as JSON)
+     */
+    body: any;
+    /**
+     * Parameters to add to the URL
+     */
+    urlSearchParams?: Object | URLSearchParams | undefined;
+    /**
+     * HTTP headers as name-value pairs
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Whether to include credentials
+     */
+    withCredentials?: boolean | undefined;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Handler for abort/timeout control
+     */
+    requestHandler?: RequestHandler | undefined;
+    /**
+     * CORS mode ('cors', 'no-cors', 'same-origin')
+     */
+    mode?: string | undefined;
+    /**
+     * Cache mode ('default', 'no-cache', etc.)
+     */
+    cache?: string | undefined;
+    /**
+     * Redirect mode ('follow', 'error', 'manual')
+     */
+    redirect?: string | undefined;
+    /**
+     * Referrer policy
+     */
+    referrerPolicy?: string | undefined;
+    /**
+     * Enable or disabled automatic caching
+     */
+    cacheEnabled?: boolean | undefined;
+};
+export type JsonDeleteOptions = {
+    /**
+     * URL string or URL object for the request
+     */
+    url: string | URL;
+    /**
+     * Parameters to add to the URL
+     */
+    urlSearchParams?: Object | URLSearchParams | undefined;
+    /**
+     * HTTP headers as name-value pairs
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Whether to include credentials
+     */
+    withCredentials?: boolean | undefined;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Handler for abort/timeout control
+     */
+    requestHandler?: RequestHandler | undefined;
+    /**
+     * CORS mode ('cors', 'no-cors', 'same-origin')
+     */
+    mode?: string | undefined;
+    /**
+     * Cache mode ('default', 'no-cache', etc.')
+     */
+    cache?: string | undefined;
+    /**
+     * Redirect mode ('follow', 'error', 'manual')
+     */
+    redirect?: string | undefined;
+    /**
+     * Referrer policy
+     */
+    referrerPolicy?: string | undefined;
+    /**
+     * Enable or disabled automatic caching
+     */
+    cacheEnabled?: boolean | undefined;
+};
 export type StaleInfo = {
     /**
      * Whether the response contains stale data