@karpeleslab/klbfw 0.1.12 → 0.2.0

package/CLAUDE.md

@@ -0,0 +1,50 @@
+# KarpelesLab Frontend Framework (klbfw) Guidelines
+
+## Commands
+```
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Code Style Guidelines
+
+### Formatting
+- Use 'use strict' directive at top of files
+- 4-space indentation (configured in vim: et:ts=4:sw=4)
+- Use semicolons consistently
+- Use single quotes for strings
+
+### Imports/Exports
+- Use CommonJS module system (require/module.exports)
+- Export using module.exports.<func> = <func>
+
+### Variables & Functions
+- Use camelCase for variables and functions
+- Use snake_case for some function names (rest_get, get_timezone_data)
+- Function declarations: mix of standard functions and arrow functions
+
+### Error Handling
+- Use Promise-based error handling with reject/resolve pattern
+- Include descriptive error objects with properties (message, body, headers)
+- Check input parameters and provide defaults (params = params || {})
+
+### Browser Compatibility
+- Check for feature availability before using (typeof window, Intl.DateTimeFormat)
+- Handle both browser and non-browser environments
+
+### Documentation
+- Include comments for complex functions
+- Add function descriptions where appropriate
+
+### Testing
+- Tests are written using Jest
+- Test modules are in the test/ directory
+- Each module has a separate test file
+- Tests should cover both SSR and client modes
+- Use setup.js for test utilities and mocks

package/README.md

@@ -1,95 +1,259 @@
 # klbfw
 
-Karpeles Lab framework lib
+Karpeles Lab Frontend Framework - A JavaScript library for communicating with KLB API.
 
-This lib is used on frontend sites to communicate through the KLB API.
+This library provides a unified interface for interacting with KLB API services from both browser and Node.js environments.
+
+## Features
+
+- **Cross-environment compatibility**: Works in both browser and Node.js environments
+- **REST API client**: Simple and consistent interface for API requests
+- **File upload**: Supports file uploads in any environment with both direct PUT and AWS S3 multipart protocols
+- **Context handling**: Manages authentication, locale, and other contextual information
+- **Cookie management**: Cross-platform cookie handling that works in SSR mode
+- **Internationalization**: Easy access to i18n data
+
+## Installation
+
+```bash
+npm install @karpeleslab/klbfw
+```
+
+For Node.js environments with file upload support, install optional dependencies:
+
+```bash
+npm install @karpeleslab/klbfw node-fetch xmldom
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run integration tests (requires KLB API server)
+npm run test:integration
+```
+
+## Version 0.2.0 Changes
+
+- **Modern JavaScript**: Refactored to use ES6+ features (arrow functions, const/let, template literals)
+- **Improved Documentation**: Added comprehensive JSDoc comments for all modules and functions
+- **Better Code Organization**: Restructured code for improved readability and maintainability
+- **Cross-Platform Support**: Enhanced environment detection and compatibility
+- **Standardized Naming**: Consistent use of camelCase with backward compatibility for legacy APIs
+- **Enhanced Error Handling**: More robust error handling and reporting
 
 # API
 
-## rest(api, method, params, context)
+## REST API Methods
+
+### rest(api, method, params, context)
+
+Performs a REST query and returns a promise to the response.
+
+### rest_get(name, params) / restGet(name, params)
+
+Simplified version of rest() that uses HTTP GET. Takes a REST API endpoint name and optional parameters, returning a Promise with the response.
+
+Note: Starting from version 0.2.0, camelCase method names are also available (e.g., `restGet` instead of `rest_get`).
+
+### upload
+
+The upload module provides cross-platform file upload capabilities, supporting both browser and Node.js environments.
+
+#### Browser Usage
+
+```javascript
+// Open file picker and upload selected files
+upload.upload.init('Misc/Debug:testUpload')()
+  .then(result => console.log('Upload complete', result));
+
+// Upload a specific File object
+upload.upload.append('Misc/Debug:testUpload', fileObject)
+  .then(result => console.log('Upload complete', result));
+
+// Track progress
+upload.upload.onprogress = (status) => {
+  console.log('Progress:', status.running.map(i => i.status));
+};
+
+// Cancel an upload
+upload.upload.cancelItem(uploadId);
+```
+
+#### Node.js Usage
+
+```javascript
+// For Node.js environments, first install dependencies:
+// npm install node-fetch xmldom
+
+// Initialize upload with specific file paths
+upload.upload.init('Misc/Debug:testUpload')(['./file1.txt', './file2.jpg'])
+  .then(result => console.log('Upload complete', result));
+
+// Or create a custom file object with path
+const file = {
+  name: 'test.txt',
+  size: 1024,
+  type: 'text/plain',
+  path: '/path/to/file.txt'
+};
+upload.upload.append('Misc/Debug:testUpload', file)
+  .then(result => console.log('Upload complete', result));
+```
+
+#### Upload Management
+
+The upload module provides methods to manage active uploads:
+
+- `upload.getStatus()`: Get current upload status (queue, running, failed)
+- `upload.cancelItem(uploadId)`: Cancel an upload
+- `upload.pauseItem(uploadId)`: Pause an active upload
+- `upload.resumeItem(uploadId)`: Resume a paused upload
+- `upload.retryItem(uploadId)`: Retry a failed upload
+- `upload.deleteItem(uploadId)`: Remove an upload from the queue or failed list
+
+## Query Parameter Methods
+
+### GET
 
-Performs a rest query and returns a promise to the response.
+Object containing all URL query parameters parsed from the request.
 
-## upload.init(api, params, context)
+### Get(key)
 
-Perform an upload. This API will show a file selector and allow the user to select one or more files.
+Retrieves a specific query parameter value by key. If no key is provided, returns the entire GET object.
 
-## getPrefix()
+### flushGet()
+
+Clears the GET parameters by resetting the internal GET object to an empty object.
+
+## URL and Path Methods
+
+### getPrefix()
 
 Returns the language/etc prefix part of the URL, for example `/l/en-US`. The prefix should be inserted before the path in the URL.
 
-## getSettings()
+### getUrl()
+
+Returns the active URL.
+
+### getPath()
+
+Returns the non-prefixed request path.
+
+### trimPrefix(url)
+
+Processes a URL to separate the prefix parts from the main path. Returns an array with two elements: an object containing the identified prefixes and the remaining path.
+
+## Context and State Methods
+
+### getSettings()
 
 Returns active settings if any.
 
-## getRealm()
+### getRealm()
 
 Returns realm information.
 
-## getContext()
+### getContext()
 
 Returns current context.
 
-## setContext(ctx)
+### setContext(ctx)
 
 Modifies the current context.
 
-## getMode()
+### getInitialState()
+
+Returns the initial state passed from SSR execution (or null if no SSR was performed).
+
+### getMode()
 
-Returns the current rending mode `ssr`, `js` etc.
+Returns the current rendering mode `ssr`, `js` etc.
 
-## getHostname()
+### getHostname()
 
 Returns the hostname part of the current URL.
 
-## getRegistry()
+### getRegistry()
 
 Returns data from the registry.
 
-## getLocale()
+### getLocale()
 
 Returns the currently active locale, for example `en-US`.
 
-## getUserGroup()
+### getUserGroup()
 
 Returns `g` from context, which is the current active user group.
 
-## getCurrency()
+### getCurrency()
 
 Returns the currently selected currency, such as `USD`.
 
-## getToken()
+### getToken()
 
 Returns the CSRF token.
 
-## getUrl()
-
-Returns the active URL.
-
-## getPath()
-
-Returns the non-prefixed request path.
-
-## getUuid()
+### getUuid()
 
 Returns the UUID of the request.
 
-## getInitialState()
+### getI18N(language)
 
-Returns the initial state passed from SSR execution (or null if no SSR was performed).
+Retrieves internationalization (i18n) data for a specified language. If no language is provided, uses the current locale.
 
-# Cookie functions
+## Cookie Methods
 
-Those methods are a requirement as using things like `document.cookie` will not work in SSR mode. The methods described here will work when SSR is enabled, and will cause cookies to be added to the HTTP response.
+These methods are required as using things like `document.cookie` will not work in SSR mode. The methods described here will work when SSR is enabled, and will cause cookies to be added to the HTTP response.
 
-## getCookie(cookie)
+### getCookie(cookie)
 
 Get the value of a specific cookie.
 
-## setCookie(cookie, value)
+### setCookie(cookie, value)
 
 Sets value for a cookie.
 
-## hasCookie(cookie)
+### hasCookie(cookie)
 
 Checks for presence of a given cookie.
+
+## Cross-Platform Support
+
+As of version 0.2.0, klbfw includes improved environment detection and cross-platform utilities to support both browser and Node.js environments.
+
+### Environment Detection
+
+The library automatically detects the current environment:
+
+```javascript
+const env = {
+  isBrowser: typeof window !== 'undefined' && typeof document !== 'undefined',
+  isNode: typeof process !== 'undefined' && process.versions && process.versions.node
+};
+```
+
+### Cross-Platform Utilities
+
+Several utilities have been designed to work across environments:
+
+- **Fetch**: Uses the browser's native `fetch` or `node-fetch` in Node.js
+- **XML Parsing**: Uses the browser's `DOMParser` or `xmldom` in Node.js
+- **File Reading**: Uses `FileReader` in the browser or `fs` in Node.js
+- **Event Dispatching**: Uses `CustomEvent` in the browser or `EventEmitter` in Node.js
+
+### Node.js Requirements
+
+To use klbfw with full functionality in Node.js, install the optional dependencies:
+
+```bash
+npm install node-fetch xmldom
+```

package/cookies.js

@@ -1,70 +1,136 @@
-'use strict'
-// vim: et:ts=4:sw=4
+'use strict';
+/**
+ * @fileoverview Cookie handling utilities for KLB Frontend Framework
+ * 
+ * This module provides functions for getting, setting, and checking cookies
+ * in both browser and server-side rendering environments.
+ */
 
-module.exports.getCookie = function(cname) {
+/**
+ * Parses cookies from document.cookie
+ * @private
+ * @returns {Object} Parsed cookies as key-value pairs
+ */
+const parseCookies = () => {
+    if (typeof document === "undefined") {
+        return {};
+    }
+    
+    const cookies = {};
+    const decodedCookie = decodeURIComponent(document.cookie);
+    const cookieParts = decodedCookie.split(';');
+    
+    for (const part of cookieParts) {
+        let cookiePart = part.trim();
+        const equalsIndex = cookiePart.indexOf('=');
+        
+        if (equalsIndex > 0) {
+            const name = cookiePart.substring(0, equalsIndex);
+            const value = cookiePart.substring(equalsIndex + 1);
+            cookies[name] = value;
+        }
+    }
+    
+    return cookies;
+};
+
+/**
+ * Gets a cookie value by name
+ * @param {string} name - Cookie name
+ * @returns {string|undefined} Cookie value or undefined if not found
+ */
+const getCookie = (name) => {
+    // Check for framework cookie handling
     if (typeof FW !== "undefined") {
-        return FW.cookies[cname];
+        return FW.cookies[name];
+    }
+    
+    // Server-side rendering without framework
+    if (typeof document === "undefined") {
+        return undefined;
     }
 
-    var name = cname + "=";
-    var decodedCookie = decodeURIComponent(document.cookie);
-    var ca = decodedCookie.split(';');
-    for(var i = 0; i <ca.length; i++) {
-        var c = ca[i];
-        while (c.charAt(0) == ' ') {
-            c = c.substring(1);
-        }
-        if (c.indexOf(name) == 0) {
-            return c.substring(name.length, c.length);
+    // Browser environment without framework
+    const cookieName = name + "=";
+    const decodedCookie = decodeURIComponent(document.cookie);
+    const cookieParts = decodedCookie.split(';');
+    
+    for (const part of cookieParts) {
+        let c = part.trim();
+        if (c.indexOf(cookieName) === 0) {
+            return c.substring(cookieName.length);
         }
     }
+    
     return undefined;
 };
 
-module.exports.hasCookie = function(cname) {
+/**
+ * Checks if a cookie exists
+ * @param {string} name - Cookie name
+ * @returns {boolean} Whether the cookie exists
+ */
+const hasCookie = (name) => {
+    // Check for framework cookie handling
     if (typeof FW !== "undefined") {
-        return ((FW.cookies.hasOwnProperty(cname)) && (FW.cookies[cname]));
+        return (FW.cookies.hasOwnProperty(name) && FW.cookies[name] !== undefined);
     }
-
-    var name = cname + "=";
-    var decodedCookie = decodeURIComponent(document.cookie);
-    var ca = decodedCookie.split(';');
-    for(var i = 0; i <ca.length; i++) {
-        var c = ca[i];
-        while (c.charAt(0) == ' ') {
-            c = c.substring(1);
-        }
-        if (c.indexOf(name) == 0) {
-            return true;
-        }
+    
+    // Server-side rendering without framework
+    if (typeof document === "undefined") {
+        return false;
     }
-    return false;
+    
+    // Browser environment without framework
+    return getCookie(name) !== undefined;
 };
 
-module.exports.setCookie = function(cname, value, exdays) {
+/**
+ * Sets a cookie
+ * @param {string} name - Cookie name
+ * @param {string} value - Cookie value
+ * @param {number} exdays - Expiration days (0 or negative for session cookie)
+ */
+const setCookie = (name, value, exdays) => {
+    // Check for framework cookie handling
     if (typeof FW !== "undefined") {
-        // always override value
-        FW.cookies[cname] = value;
+        // Always override value
+        FW.cookies[name] = value;
     }
 
-    var d = undefined;
+    // Calculate expiration if needed
+    let d;
     if (exdays > 0) {
         d = new Date();
-        d.setTime(d.getTime() + (exdays*24*60*60*1000));
+        d.setTime(d.getTime() + (exdays * 24 * 60 * 60 * 1000));
     }
+    
+    // Server-side rendering
     if (typeof __platformSetCookie !== "undefined") {
-        // ssr mode
-        return __platformSetCookie(cname, value, d);
+        return __platformSetCookie(name, value, d);
     }
+    
+    // Server-side without cookie handling
+    if (typeof document === "undefined") {
+        return;
+    }
+    
+    // Handle cookie deletion
     if (typeof value === "undefined") {
-        // remove cookie
-        document.cookie = cname+"=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/";
+        document.cookie = name + "=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/";
         return;
     }
 
-    var expires;
+    // Set cookie in browser
+    let expires = "";
     if (d) {
-        expires = "expires="+ d.toUTCString();
+        expires = "expires=" + d.toUTCString();
     }
-    document.cookie = cname + "=" + value + ";" + expires + ";path=/;secure;samesite=none";
+    
+    document.cookie = name + "=" + value + ";" + expires + ";path=/;secure;samesite=none";
 };
+
+// Export functions
+module.exports.getCookie = getCookie;
+module.exports.hasCookie = hasCookie;
+module.exports.setCookie = setCookie;