@markwharton/pwa-core 1.2.0 → 1.2.1

package/dist/http/responses.js

@@ -10,7 +10,11 @@ exports.isNotFoundError = isNotFoundError;
 exports.isConflictError = isConflictError;
 const status_1 = require("./status");
 /**
- * Create a 400 Bad Request response
+ * Creates a 400 Bad Request response.
+ * @param message - The error message to return
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!body.email) return badRequestResponse('Email is required');
  */
 function badRequestResponse(message) {
     return {
@@ -19,7 +23,11 @@ function badRequestResponse(message) {
     };
 }
 /**
- * Create a 401 Unauthorized response
+ * Creates a 401 Unauthorized response.
+ * @param message - The error message (default: 'Unauthorized')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!token) return unauthorizedResponse();
  */
 function unauthorizedResponse(message = 'Unauthorized') {
     return {
@@ -28,7 +36,11 @@ function unauthorizedResponse(message = 'Unauthorized') {
     };
 }
 /**
- * Create a 403 Forbidden response
+ * Creates a 403 Forbidden response.
+ * @param message - The error message (default: 'Forbidden')
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!isAdmin(payload)) return forbiddenResponse('Admin access required');
  */
 function forbiddenResponse(message = 'Forbidden') {
     return {
@@ -37,7 +49,12 @@ function forbiddenResponse(message = 'Forbidden') {
     };
 }
 /**
- * Create a 404 Not Found response
+ * Creates a 404 Not Found response.
+ * @param resource - The name of the resource that wasn't found
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (!user) return notFoundResponse('User');
+ * // Returns: { error: 'User not found' }
  */
 function notFoundResponse(resource) {
     return {
@@ -46,7 +63,11 @@ function notFoundResponse(resource) {
     };
 }
 /**
- * Create a 409 Conflict response
+ * Creates a 409 Conflict response.
+ * @param message - The conflict error message
+ * @returns Azure Functions HttpResponseInit object
+ * @example
+ * if (existingUser) return conflictResponse('Email already registered');
  */
 function conflictResponse(message) {
     return {
@@ -55,7 +76,17 @@ function conflictResponse(message) {
     };
 }
 /**
- * Handle unexpected errors safely (logs details, returns generic message)
+ * Handles unexpected errors safely by logging details and returning a generic message.
+ * Use in catch blocks to avoid exposing internal error details to clients.
+ * @param error - The caught error
+ * @param context - Azure Functions InvocationContext for logging
+ * @returns Azure Functions HttpResponseInit with 500 status
+ * @example
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   return handleFunctionError(error, context);
+ * }
  */
 function handleFunctionError(error, context) {
     const message = error instanceof Error ? error.message : 'Unknown error';
@@ -66,7 +97,16 @@ function handleFunctionError(error, context) {
     };
 }
 /**
- * Check if an Azure Table Storage error is "not found"
+ * Checks if an error is an Azure Table Storage "not found" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 404
+ * @example
+ * try {
+ *   await tableClient.getEntity(pk, rk);
+ * } catch (error) {
+ *   if (isNotFoundError(error)) return notFoundResponse('Entity');
+ *   throw error;
+ * }
  */
 function isNotFoundError(error) {
     return (error instanceof Error &&
@@ -74,7 +114,16 @@ function isNotFoundError(error) {
         error.statusCode === 404);
 }
 /**
- * Check if an Azure Table Storage error is "conflict"
+ * Checks if an error is an Azure Table Storage "conflict" error.
+ * @param error - The caught error
+ * @returns True if error has statusCode 409
+ * @example
+ * try {
+ *   await tableClient.createEntity(entity);
+ * } catch (error) {
+ *   if (isConflictError(error)) return conflictResponse('Entity already exists');
+ *   throw error;
+ * }
  */
 function isConflictError(error) {
     return (error instanceof Error &&

package/dist/storage/client.d.ts

@@ -1,25 +1,48 @@
 import { TableClient } from '@azure/data-tables';
 /**
- * Initialize storage configuration - call once at startup
+ * Initializes Azure Table Storage configuration. Call once at application startup.
+ * @param config - Storage configuration options
+ * @param config.accountName - Azure Storage account name (for managed identity)
+ * @param config.connectionString - Connection string (for local development)
+ * @example
+ * // Production (Azure with managed identity)
+ * initStorage({ accountName: 'mystorageaccount' });
+ *
+ * // Local development (Azurite)
+ * initStorage({ connectionString: 'UseDevelopmentStorage=true' });
  */
 export declare function initStorage(config: {
     accountName?: string;
     connectionString?: string;
 }): void;
 /**
- * Auto-initialize from environment variables
+ * Initializes storage from environment variables.
+ * Reads STORAGE_ACCOUNT_NAME and AzureWebJobsStorage.
+ * @example
+ * initStorageFromEnv(); // Uses process.env automatically
  */
 export declare function initStorageFromEnv(): void;
 /**
- * Check if using managed identity (Azure) vs connection string (local)
+ * Checks if using Azure managed identity vs local connection string.
+ * @returns True if using managed identity (production), false for connection string (local)
  */
 export declare function useManagedIdentity(): boolean;
 /**
- * Get a TableClient for the specified table
- * Creates table if it doesn't exist, caches client for reuse
+ * Gets a TableClient for the specified table, creating the table if needed.
+ * Clients are cached for reuse across requests.
+ * @param tableName - The Azure Table Storage table name
+ * @returns A configured TableClient instance
+ * @throws Error if storage is not configured
+ * @example
+ * const client = await getTableClient('users');
+ * await client.createEntity({ partitionKey: 'pk', rowKey: 'rk', name: 'John' });
  */
 export declare function getTableClient(tableName: string): Promise<TableClient>;
 /**
- * Clear the client cache (useful for testing)
+ * Clears the TableClient cache. Primarily useful for testing.
+ * @example
+ * afterEach(() => {
+ *   clearTableClientCache();
+ * });
  */
 export declare function clearTableClientCache(): void;

package/dist/storage/client.js

@@ -16,14 +16,26 @@ const tableClients = new Map();
 let storageAccountName;
 let connectionString;
 /**
- * Initialize storage configuration - call once at startup
+ * Initializes Azure Table Storage configuration. Call once at application startup.
+ * @param config - Storage configuration options
+ * @param config.accountName - Azure Storage account name (for managed identity)
+ * @param config.connectionString - Connection string (for local development)
+ * @example
+ * // Production (Azure with managed identity)
+ * initStorage({ accountName: 'mystorageaccount' });
+ *
+ * // Local development (Azurite)
+ * initStorage({ connectionString: 'UseDevelopmentStorage=true' });
  */
 function initStorage(config) {
     storageAccountName = config.accountName;
     connectionString = config.connectionString;
 }
 /**
- * Auto-initialize from environment variables
+ * Initializes storage from environment variables.
+ * Reads STORAGE_ACCOUNT_NAME and AzureWebJobsStorage.
+ * @example
+ * initStorageFromEnv(); // Uses process.env automatically
  */
 function initStorageFromEnv() {
     initStorage({
@@ -32,14 +44,21 @@ function initStorageFromEnv() {
     });
 }
 /**
- * Check if using managed identity (Azure) vs connection string (local)
+ * Checks if using Azure managed identity vs local connection string.
+ * @returns True if using managed identity (production), false for connection string (local)
  */
 function useManagedIdentity() {
     return !!storageAccountName && !connectionString?.includes('UseDevelopmentStorage');
 }
 /**
- * Get a TableClient for the specified table
- * Creates table if it doesn't exist, caches client for reuse
+ * Gets a TableClient for the specified table, creating the table if needed.
+ * Clients are cached for reuse across requests.
+ * @param tableName - The Azure Table Storage table name
+ * @returns A configured TableClient instance
+ * @throws Error if storage is not configured
+ * @example
+ * const client = await getTableClient('users');
+ * await client.createEntity({ partitionKey: 'pk', rowKey: 'rk', name: 'John' });
  */
 async function getTableClient(tableName) {
     // Return cached client if available
@@ -77,7 +96,11 @@ async function getTableClient(tableName) {
     return client;
 }
 /**
- * Clear the client cache (useful for testing)
+ * Clears the TableClient cache. Primarily useful for testing.
+ * @example
+ * afterEach(() => {
+ *   clearTableClientCache();
+ * });
  */
 function clearTableClientCache() {
     tableClients.clear();

package/dist/types.d.ts

@@ -22,14 +22,27 @@ export interface Result<T> {
     statusCode?: number;
 }
 /**
- * Helper to create a success result
+ * Creates a success result with data.
+ * @param data - The success payload
+ * @returns A Result with ok=true and the provided data
+ * @example
+ * return ok({ user: 'john', role: 'admin' });
  */
 export declare function ok<T>(data: T): Result<T>;
 /**
- * Helper to create a success result with no data
+ * Creates a success result with no data.
+ * @returns A Result with ok=true and no data
+ * @example
+ * return okVoid(); // { ok: true }
  */
 export declare function okVoid(): Result<void>;
 /**
- * Helper to create a failure result
+ * Creates a failure result with an error message.
+ * @param error - The error message
+ * @param statusCode - Optional HTTP status code for API/push operations
+ * @returns A Result with ok=false and the error details
+ * @example
+ * return err('Token expired');
+ * return err('Subscription gone', 410);
  */
 export declare function err<T>(error: string, statusCode?: number): Result<T>;

package/dist/types.js

@@ -7,19 +7,32 @@ exports.ok = ok;
 exports.okVoid = okVoid;
 exports.err = err;
 /**
- * Helper to create a success result
+ * Creates a success result with data.
+ * @param data - The success payload
+ * @returns A Result with ok=true and the provided data
+ * @example
+ * return ok({ user: 'john', role: 'admin' });
  */
 function ok(data) {
     return { ok: true, data };
 }
 /**
- * Helper to create a success result with no data
+ * Creates a success result with no data.
+ * @returns A Result with ok=true and no data
+ * @example
+ * return okVoid(); // { ok: true }
  */
 function okVoid() {
     return { ok: true };
 }
 /**
- * Helper to create a failure result
+ * Creates a failure result with an error message.
+ * @param error - The error message
+ * @param statusCode - Optional HTTP status code for API/push operations
+ * @returns A Result with ok=false and the error details
+ * @example
+ * return err('Token expired');
+ * return err('Subscription gone', 410);
  */
 function err(error, statusCode) {
     return statusCode !== undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/pwa-core",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Shared patterns for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",