@hkdigital/lib-core 0.4.55 → 0.4.56

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

package/dist/network/http/typedef.js

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

package/dist/services/README.md

@@ -204,22 +204,31 @@ await manager.stopAll();
 Services receive helpful utilities in their constructor options for accessing other services:
 
 ```javascript
+/**
+ * Example service that depends on other services
+ */
 class AuthService extends ServiceBase {
+  /** @type {(<T>(serviceName: string) => T)} */
+  #getService;
+
+  /** @type {() => import('$hklib-core/services/index.js').ServiceManager} */
+  #getManager;
+
   constructor(serviceName, options) {
     super(serviceName, options);
     
-    // Store service access utilities
-    this.getManager = options.getManager;   // Function to get manager (lazy)
-    this.getService = options.getService;   // Bound getService function
+    // Store service access utilities as private methods
+    this.#getService = options.getService;   // Bound getService function
+    this.#getManager = options.getManager;   // Function to get manager (lazy)
   }
   
   async authenticateUser(credentials) {
     // Access other services with full type safety and error checking
-    const database = this.getService('database');
+    const database = this.#getService('database');
     const user = await database.findUser(credentials.username);
     
-    // Access manager for advanced operations
-    const manager = this.getManager();
+    // Access manager for advanced operations when needed
+    const manager = this.#getManager();
     const health = await manager.checkHealth();
     
     return user;
@@ -227,6 +236,48 @@ class AuthService extends ServiceBase {
 }
 ```
 
+**Best Practice Pattern:**
+
+The recommended approach is to store service access functions as **private methods** using the hash prefix. This pattern:
+
+- **Keeps the API clean** - No public getService/getManager methods exposed
+- **Prevents serialization issues** - Private fields don't serialize to JSON
+- **Enforces proper encapsulation** - Service dependencies stay internal
+- **Provides type safety** - Full generic support with `this.#getService<DatabaseService>('database')`
+
+```javascript
+/**
+ * Unified service for tracking complete player data including progress and 
+ * profile matches
+ */
+export default class PlayerService extends ServiceBase {
+  
+  /** @type {(<T>(serviceName: string) => T)} */
+  #getService;
+
+  /**
+   * @param {string} serviceName
+   * @param {import('$hklib-core/services/typedef.js').ServiceOptions} [options]
+   */
+  constructor(serviceName, options) {
+    super(serviceName, options);
+
+    this.#getService = options?.getService;
+  }
+
+  async getPlayerProfile(playerId) {
+    // Access dependent services cleanly
+    const database = this.#getService('database');
+    const analytics = this.#getService('analytics');
+    
+    const profile = await database.getPlayer(playerId);
+    const stats = await analytics.getPlayerStats(playerId);
+    
+    return { ...profile, stats };
+  }
+}
+```
+
 **Service Access Methods:**
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.4.55",
+	"version": "0.4.56",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"