https://github.com/karpeleslab/klbfw
KarpelesLab framework module for frontend code
https://github.com/karpeleslab/klbfw
Last synced: 4 months ago
JSON representation
KarpelesLab framework module for frontend code
- Host: GitHub
- URL: https://github.com/karpeleslab/klbfw
- Owner: KarpelesLab
- License: mit
- Created: 2019-12-18T02:42:07.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-05-01T04:25:45.000Z (about 1 year ago)
- Last Synced: 2025-07-01T00:08:50.042Z (12 months ago)
- Language: JavaScript
- Homepage:
- Size: 263 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# klbfw
Karpeles Lab Frontend Framework - A JavaScript library for communicating with 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/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 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.init('Misc/Debug:testUpload')()
.then(result => console.log('Upload complete', result));
// Open file picker with custom parameters and notification callback
upload.init('Support/Ticket:upload', {image_variation: 'alias=mini&strip&scale_crop=300x200'}, (result) => {
if (result.status == 'complete') console.log(result.final);
});
// Upload a specific File object
upload.append('Misc/Debug:testUpload', fileObject)
.then(result => console.log('Upload complete', result));
// Track progress
upload.onprogress = (status) => {
console.log('Progress:', status.running.map(i => i.status));
};
// Cancel an upload
upload.cancelItem(uploadId);
```
#### Node.js Usage
```javascript
// For Node.js environments, first install dependencies:
// npm install node-fetch @xmldom/xmldom
// Initialize upload with specific file paths
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.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
Object containing all URL query parameters parsed from the request.
### Get(key)
Retrieves a specific query parameter value by key. If no key is provided, returns the entire GET object.
### 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.
### 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()
Returns realm information.
### getContext()
Returns current context.
### setContext(ctx)
Modifies the current context.
### getInitialState()
Returns the initial state passed from SSR execution (or null if no SSR was performed).
### getMode()
Returns the current rendering mode `ssr`, `js` etc.
### getHostname()
Returns the hostname part of the current URL.
### getRegistry()
Returns data from the registry.
### getLocale()
Returns the currently active locale, for example `en-US`.
### getUserGroup()
Returns `g` from context, which is the current active user group.
### getCurrency()
Returns the currently selected currency, such as `USD`.
### getToken()
Returns the CSRF token.
### getUuid()
Returns the UUID of the request.
### getI18N(language)
Retrieves internationalization (i18n) data for a specified language. If no language is provided, uses the current locale.
## Cookie Methods
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)
Get the value of a specific cookie.
### setCookie(cookie, value)
Sets value for a 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/xmldom
```