@aegis-framework/artemis 0.4.1 → 0.5.1

package/README.md

@@ -1,168 +1,627 @@
 # Artemis
 
-Artemis is a JavaScript Library that aims to provide common utilities needed during development such as DOM manipulation, a wrapper for client based Storage and other functions that may be useful for web app development.
+Artemis is a lightweight JavaScript/TypeScript library providing common utilities for web development including DOM manipulation, storage wrappers, HTTP requests, and platform detection.
 
-## Using it
-Artemis is provided as a CommonJS, ES6 and global library.
+## Installation
 
-### Browser
+```bash
+# Using npm
+npm install @aegis-framework/artemis
 
-```html
-<script src='./artemis.min.js'></script>
-```
+# Using yarn
+yarn add @aegis-framework/artemis
 
-```javascript
-const { $_, Text } = Artemis;
+# Using bun
+bun add @aegis-framework/artemis
 ```
 
-### ES6 Modules
+### ES Modules
 
 ```javascript
-import { $_, Text } from '@aegis-framework/artemis';
+import { $_, Text, Space, SpaceAdapter } from '@aegis-framework/artemis';
 ```
 
-### Node JS
+### Browser (Script Tag)
 
-```javascript
-const { $_, Text } = require ('@aegis-framework/artemis');
+```html
+<script src="path/to/artemis.browser.js"></script>
+<script>
+  const { $_, Text, Space, SpaceAdapter } = Artemis;
+</script>
 ```
 
-
-Below are some simple examples but you can read the full [documentation of each class](https://gitlab.com/AegisFramework/Artemis/tree/master/docs) for more details.
+---
 
 ## Classes
 
 ### DOM
-Artemis core library focuses on DOM manipulation, providing a jQuery-like experience and API
+
+jQuery-like DOM manipulation with a modern API.
 
 ```javascript
-$_ready (()=> {
-	$_('body').append ('<h1>Some Title</h1>');
-    $_('h1').text ('A different title');
-    $_('h1').style ('color', '#424242');
+import { $_, $_ready, $_create } from '@aegis-framework/artemis';
+
+$_ready(() => {
+  // Select and manipulate elements
+  $_('h1').text('Hello World').addClass('title');
+
+  // Chained operations
+  $_('.card')
+    .addClass('active')
+    .style({ 'background-color': '#fff', 'padding': '1rem' })
+    .fadeIn(400);
+
+  // Event handling
+  $_('button').click((e) => {
+    console.log('Button clicked!');
+  });
+
+  // Event delegation
+  $_('ul').on('click', 'li', (e) => {
+    console.log('List item clicked:', e.target);
+  });
+
+  // Removing event handlers
+  const handler = (e) => console.log('Clicked!');
+  $_('button').on('click', handler);
+  $_('button').off('click', handler);       // Remove specific handler
+  $_('button').off('click');                // Remove all click handlers
+  $_('button').off();                       // Remove all handlers
+
+  // Create new elements
+  const div = $_create('div', { class: 'container', id: 'main' });
+
+  // Traversal
+  $_('.item').parent().addClass('has-item');
+  $_('.item').siblings().removeClass('active');
+  $_('.item').next().addClass('following');
+
+  // Animations
+  $_('#box').fadeOut(400, () => console.log('Hidden'));
+  $_('#box').fadeIn(400, () => console.log('Visible'));
+  $_('#box').animate(
+    [{ transform: 'scale(1)' }, { transform: 'scale(1.2)' }],
+    { duration: 300, fill: 'forwards' }
+  );
 });
 ```
 
-### Form
-Artemis also includes a small form utility class that helps with filling and retrieving values from a form.
+#### Key Methods
+
+| Method | Description |
+|--------|-------------|
+| `addClass(name)` | Add a class |
+| `removeClass(name?)` | Remove class(es) |
+| `toggleClass(names)` | Toggle space-separated classes |
+| `hasClass(name)` | Check if all elements have class |
+| `text(value?)` | Get/set text content |
+| `html(value?)` | Get/set HTML content |
+| `value(value?)` | Get/set form element value |
+| `attribute(name, value?)` | Get/set attribute |
+| `data(name, value?)` | Get/set data attributes |
+| `style(prop, value?)` | Get/set inline styles |
+| `on(event, callback)` | Add event listener |
+| `on(event, selector, callback)` | Add delegated event listener |
+| `off(event?, selectorOrCallback?, callback?)` | Remove event listener(s) |
+| `trigger(event, detail?)` | Dispatch custom event |
+| `find(selector)` | Find descendants |
+| `closest(selector)` | Find closest ancestor |
+| `parent()` | Get parent elements |
+| `parents()` | Get all ancestors |
+| `children()` | Get child elements |
+| `siblings()` | Get sibling elements |
+| `next()` | Get next sibling |
+| `prev()` | Get previous sibling |
+| `first()` | Get first element |
+| `last()` | Get last element |
+| `eq(index)` | Get element at index |
+| `append(content)` | Append content |
+| `prepend(content)` | Prepend content |
+| `remove()` | Remove elements |
+| `empty()` | Clear children |
+| `clone(deep?)` | Clone elements |
+| `fadeIn(duration, callback?)` | Fade in animation |
+| `fadeOut(duration, callback?)` | Fade out animation |
+| `animate(keyframes, options)` | Web Animations API |
+
+---
 
-```html
-<form data-form="MyForm">
-	<input type="text" name="SomeInput">
-	<input type="text" name="OtherInput">
-</form>
-```
+### Space
+
+Storage wrapper with namespacing, versioning, and multiple backend adapters.
 
 ```javascript
-Form.fill ('MyForm', {
-	'SomeInput': 'Here is some Value',
-    'OtherInput': 'And here’s another one'
+import { Space, SpaceAdapter } from '@aegis-framework/artemis';
+
+// LocalStorage adapter
+const storage = new Space(SpaceAdapter.LocalStorage, {
+  name: 'MyApp',
+  version: '1.0.0'
 });
 
-console.log (Form.values ('MyForm'));
+await storage.open();
+
+// Basic operations
+await storage.set('user', { name: 'John', age: 30 });
+const user = await storage.get('user');
+await storage.update('user', { age: 31 }); // Merges with existing
+await storage.remove('user');
+await storage.clear();
+
+// Get all data
+const allData = await storage.getAll();
+const keys = await storage.keys();
+
+// Iterate
+await storage.each((key, value) => {
+  console.log(key, value);
+});
+
+// Check existence
+await storage.contains('user'); // Resolves if exists, rejects if not
+
+// Callbacks
+storage.onCreate((key, value) => console.log('Created:', key));
+storage.onUpdate((key, value) => console.log('Updated:', key));
+storage.onDelete((key, value) => console.log('Deleted:', key));
+
+// Transformations (modify data on get/set)
+storage.addTransformation({
+  id: 'timestamps',
+  set: (key, value) => ({ ...value, updatedAt: Date.now() }),
+  get: (key, value) => value
+});
 ```
 
-### Space
+#### Adapters
 
-The Space Library is a wrapper for simple storage solutions as Local and Session storage but provides data independence through storage namespaces and versioning.
+**LocalStorage** - Persistent browser storage
+```javascript
+new Space(SpaceAdapter.LocalStorage, { name: 'App', version: '1.0.0' });
+```
 
+**SessionStorage** - Session-only storage
 ```javascript
-let space = new Space (SpaceAdapter.LocalStorage, {
-	name: 'Storage',
-	version: '0.1.0'
-});
+new Space(SpaceAdapter.SessionStorage, { name: 'App', version: '1.0.0' });
+```
 
-space.set ('Test', {
-    value: 'Some Value'
-}).then (({key, value}) => {
-    console.log ('The value was inserted correctly!');
+**IndexedDB** - Large-scale structured storage
+```javascript
+new Space(SpaceAdapter.IndexedDB, {
+  name: 'App',
+  version: '1.0.0',
+  store: 'users',
+  props: { keyPath: 'id', autoIncrement: true },
+  index: {
+    email: { name: 'Email Index', field: 'email', props: { unique: true } }
+  }
 });
+```
 
-space.get ('Test').then ((value) => {
-    return value;
-}).then (({key, value}) => {
-    console.log (value);
+**RemoteStorage** - REST API backend
+```javascript
+new Space(SpaceAdapter.RemoteStorage, {
+  name: 'App',
+  version: '1.0.0',
+  endpoint: 'https://api.example.com/',
+  store: 'users'
 });
+```
+
+#### Version Upgrades
 
-space = new Space (SpaceAdapter.LocalStorage, {
-	name: 'Storage',
-	version: '0.1.1'
+```javascript
+const storage = new Space(SpaceAdapter.LocalStorage, {
+  name: 'App',
+  version: '2.0.0'
 });
 
-space.upgrade ('0.1.0', '0.1.1', (storage) => {
-    return storage.set ('Test', {
-		value: 'Other Value'
-	});
+// Define upgrades before opening
+await storage.upgrade('1.0.0', '2.0.0', async (adapter) => {
+  const oldData = await adapter.get('config');
+  await adapter.set('config', { ...oldData, newField: 'value' });
 });
+
+await storage.open(); // Upgrades run automatically
 ```
 
+---
+
 ### Request
-The request library provides a simple way to send HTTP requests using the fetch API.
+
+HTTP client built on the Fetch API with timeout support and error handling.
 
 ```javascript
-Request.get ('https://example.com/api/', {
-	'someQueryParam': 'Some Query Value!'
-}).then ((response) => {
-	return response.text ();
-}).then ((text) => {
-	console.log (text);
+import { Request, RequestError, RequestTimeoutError } from '@aegis-framework/artemis';
+
+// GET request
+const response = await Request.get('https://api.example.com/users', {
+  page: 1,
+  limit: 10
 });
 
-Request.post ('https://example.com/api/', {
-	'someKey': 'Some Value!'
-}).then ((response) => {
-	return response.text ();
-}).then ((text) => {
-	console.log (text);
+// POST with JSON
+const created = await Request.postJson('https://api.example.com/users', {
+  name: 'John',
+  email: 'john@example.com'
 });
+
+// PUT, PATCH, DELETE
+await Request.put(url, data);
+await Request.patch(url, data);
+await Request.delete(url);
+
+// HEAD request (check if resource exists)
+const exists = await Request.exists('https://api.example.com/users/1');
+
+// With timeout
+const data = await Request.json('https://api.example.com/slow', {}, {
+  timeout: 5000 // 5 seconds
+});
+
+// Different response types
+const json = await Request.json(url);
+const text = await Request.text(url);
+const blob = await Request.blob(url);
+const buffer = await Request.arrayBuffer(url);
+
+// Custom headers
+await Request.post(url, data, {
+  headers: {
+    'Authorization': 'Bearer token',
+    'Content-Type': 'application/json'
+  }
+});
+
+// Error handling
+try {
+  const data = await Request.json(url);
+} catch (error) {
+  if (error instanceof RequestError) {
+    console.log('HTTP Error:', error.status, error.statusText);
+  } else if (error instanceof RequestTimeoutError) {
+    console.log('Request timed out');
+  }
+}
+
+// Serialize data to query string
+const query = Request.serialize({ name: 'John', tags: ['a', 'b'] });
 ```
 
-### Platform
-The platform library provides several utility methods to obtain information about the platform in which the code is running.
+---
+
+### Form
+
+Form filling and value retrieval utilities.
+
+```html
+<form data-form="UserForm">
+  <input type="text" name="username">
+  <input type="email" name="email">
+  <input type="number" name="age">
+  <input type="checkbox" name="newsletter">
+  <select name="country">
+    <option value="us">USA</option>
+    <option value="uk">UK</option>
+  </select>
+</form>
+```
 
 ```javascript
-if (Platform.mobile ('Android')) {
-	console.log ('You are running this on Android!');
-} else if (Platform.mobile ()) {
-	console.log ('You are running this on some kind of mobile device!');
-} else if (Platform.desktop ('macOS')) {
-	console.log ('You are running this on a Mac!');
-}
+import { Form } from '@aegis-framework/artemis';
+
+// Fill form with data
+Form.fill('UserForm', {
+  username: 'john_doe',
+  email: 'john@example.com',
+  age: 30,
+  newsletter: true,
+  country: 'us'
+});
+
+// Get form values with type parsing
+const values = Form.values('UserForm', {
+  parseNumbers: true,  // Parse number inputs as numbers
+  parseBooleans: true  // Parse single checkboxes as booleans
+});
+// { username: 'john_doe', email: '...', age: 30, newsletter: true, country: 'us' }
 
-if (Platform.electron ()) {
-	console.log ('You are running this on a Electron!');
-} else if (Platform.cordova ()) {
-	console.log ('You are running this on a Cordova!');
+// Reset form
+Form.reset('UserForm');
+
+// Validation
+if (Form.isValid('UserForm')) {
+  // Submit form
 }
+
+// Show validation messages
+Form.reportValidity('UserForm');
+```
+
+---
+
+### Platform
+
+Platform and feature detection.
+
+```javascript
+import { Platform } from '@aegis-framework/artemis';
+
+// Device type
+Platform.desktop();           // true if desktop
+Platform.desktop('macOS');    // true if macOS
+Platform.desktop('Windows');  // true if Windows
+Platform.desktop('Linux');    // true if Linux
+
+Platform.mobile();            // true if any mobile
+Platform.mobile('iOS');       // true if iPhone/iPod
+Platform.mobile('iPadOS');    // true if iPad
+Platform.mobile('Android');   // true if Android
+
+// Display
+Platform.orientation;    // 'portrait' | 'landscape'
+Platform.portrait;       // true if portrait
+Platform.landscape;      // true if landscape
+Platform.retina;         // true if high DPI display
+
+// Input
+Platform.touch;          // true if touch supported
+Platform.canHover;       // true if hover supported
+Platform.coarsePointer;  // true if touch is primary
+Platform.finePointer;    // true if mouse is primary
+
+// User preferences
+Platform.darkMode;       // true if dark mode preferred
+Platform.reducedMotion;  // true if reduced motion preferred
+
+// Runtime environment
+Platform.electron;       // true if Electron
+Platform.cordova;        // true if Cordova/PhoneGap
+Platform.standalone;     // true if installed PWA
+
+// Features
+Platform.serviceWorkers; // true if service workers supported
 ```
 
+---
+
 ### Text
-The text library provides simple utility methods to perform text transformations or other text related functions.
+
+Text transformation utilities.
 
 ```javascript
-console.log (Text.capitalize ('is this text capitalized?'));
-// Logs: Is This Text Capitalized?
+import { Text } from '@aegis-framework/artemis';
+
+// Capitalize words
+Text.capitalize('hello world');                    // 'Hello World'
+Text.capitalize('API docs', { preserveCase: true }); // 'API Docs'
+
+// URL-friendly slug
+Text.friendly('Hello World!');  // 'hello-world'
+Text.friendly('Café Münich');   // 'cafe-munich'
 
-console.log (Text.suffix ('Hello', 'Hello how are you?'));
-// Logs: how are you?
+// Truncate with ellipsis
+Text.truncate('Long text here', 10);        // 'Long te...'
+Text.truncate('Long text', 10, '…');        // 'Long text'
 
-console.log (Text.prefix ('how are you?', 'Hello how are you?'));
-// Logs: Hello
+// Extract parts
+Text.prefix('@', 'user@example.com');  // 'user'
+Text.suffix('@', 'user@example.com');  // 'example.com'
+
+// Check for blank
+Text.isBlank('');      // true
+Text.isBlank('  ');    // true
+Text.isBlank(null);    // true
+Text.isBlank('text');  // false
+
+// Get selected text
+const selected = Text.selection();
 ```
 
+---
+
+### FileSystem
+
+File operations and utilities.
+
+```javascript
+import { FileSystem } from '@aegis-framework/artemis';
+
+// Read local file
+const text = await FileSystem.read(file, 'text');
+const base64 = await FileSystem.read(file, 'base64');
+const buffer = await FileSystem.read(file, 'buffer');
+const binary = await FileSystem.read(file, 'binary');
+
+// Read remote file
+const content = await FileSystem.readRemote('https://example.com/file.txt', 'text');
+
+// Create and download file
+const file = FileSystem.create('data.json', JSON.stringify(data), 'application/json');
+FileSystem.download(file);
+FileSystem.download(blob, 'custom-name.txt');
+
+// File type checks
+FileSystem.isImage('photo.jpg');   // true
+FileSystem.isVideo('movie.mp4');   // true
+FileSystem.isAudio('song.mp3');    // true
+FileSystem.extension('file.txt');  // 'txt'
+
+// Human-readable size
+FileSystem.humanSize(1536);     // '1.5 KB'
+FileSystem.humanSize(1048576);  // '1 MB'
+```
+
+---
+
 ### Util
-The util library provides diverse methods that could be useful for some applications
+
+General utilities.
 
 ```javascript
-console.log (Util.uuid ());
-// Logs: Some UUID such as 116a7d96-8c6c-46ee-a9e1-3c7183e691b5
+import { Util } from '@aegis-framework/artemis';
+
+// Generate UUID v4
+const id = Util.uuid();  // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+
+// Ensure async execution
+await Util.callAsync(someFunction, context, arg1, arg2);
+
+// Debounce (delay until quiet period)
+const debouncedSearch = Util.debounce((query) => {
+  fetch(`/search?q=${query}`);
+}, 300);
+
+input.addEventListener('input', (e) => debouncedSearch(e.target.value));
+
+// Throttle (limit call frequency)
+const throttledScroll = Util.throttle(() => {
+  console.log('Scroll position:', window.scrollY);
+}, 100);
+
+window.addEventListener('scroll', throttledScroll);
+```
+
+---
+
+### Debug
 
-function test () {
-	console.log ('A simple Function');
+Conditional console logging with debug levels.
+
+```javascript
+import { Debug, DebugLevel } from '@aegis-framework/artemis';
+
+// Set debug level
+Debug.setLevel(DebugLevel.DEBUG);  // Show all logs
+Debug.setLevel(DebugLevel.ERROR);  // Only errors
+Debug.setLevel(DebugLevel.NONE);   // Silent
+
+// Levels: NONE < ERROR < WARNING < INFO < DEBUG < ALL
+
+// Logging (respects debug level)
+Debug.log('General log');      // DEBUG+
+Debug.debug('Debug info');     // DEBUG+
+Debug.info('Information');     // INFO+
+Debug.warning('Warning!');     // WARNING+
+Debug.warn('Also warning');    // WARNING+
+Debug.error('Error!');         // ERROR+
+
+// Assertions
+Debug.assert(value > 0, 'Value must be positive');
+
+// Grouping
+Debug.group('Network requests');
+Debug.log('Request 1');
+Debug.log('Request 2');
+Debug.groupEnd();
+
+Debug.groupCollapsed('Collapsed group');
+Debug.log('Hidden by default');
+Debug.groupEnd();
+
+// Tables
+Debug.table([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }]);
+
+// Timing
+Debug.time('Operation');
+// ... do work ...
+Debug.timeLog('Operation', 'still running...');
+// ... more work ...
+Debug.timeEnd('Operation');  // Logs: Operation: 123.45ms
+
+// Counting
+Debug.count('myFunction called');  // myFunction called: 1
+Debug.count('myFunction called');  // myFunction called: 2
+Debug.countReset('myFunction called');
+
+// Object inspection
+Debug.dir(complexObject);
+Debug.dirxml(htmlElement);
+
+// Clear console
+Debug.clear();
+
+// Check level
+if (Debug.isEnabled(DebugLevel.DEBUG)) {
+  // Expensive debug operation
 }
+```
 
-Util.callAsync (test).then (() => {
-	console.log ('Test was executed and a promise was inserted so test behaves like a function using promises');
-});
+---
+
+### Preload
+
+Asset preloading utilities.
+
+```javascript
+import { Preload } from '@aegis-framework/artemis';
+
+// Preload single image
+const img = await Preload.image('/assets/hero.jpg');
+document.body.appendChild(img);
+
+// Preload multiple images
+const images = await Preload.images([
+  '/assets/1.jpg',
+  '/assets/2.jpg',
+  '/assets/3.jpg'
+]);
+
+// Preload files with priority hint
+await Preload.file('/data/config.json', 'high');
+await Preload.files(['/a.js', '/b.js'], 'low');
+
+// Preload specific asset types
+await Preload.stylesheet('/styles/main.css');
+await Preload.script('/js/vendor.js');
+await Preload.font('/fonts/custom.woff2');
+
+// Cache API integration
+const isCached = await Preload.isCached('my-cache', '/assets/image.jpg');
+await Preload.addToCache('my-cache', '/assets/image.jpg');
+await Preload.addAllToCache('my-cache', ['/a.js', '/b.js', '/c.css']);
+```
+
+---
+
+## TypeScript Support
+
+Artemis is written in TypeScript and includes full type definitions.
+
+```typescript
+import {
+  $_,
+  DOM,
+  Space,
+  SpaceAdapter,
+  Request,
+  Platform,
+  Text,
+  FileSystem,
+  Form,
+  Util,
+  Debug,
+  DebugLevel,
+  Preload
+} from '@aegis-framework/artemis';
+
+import type {
+  SpaceConfiguration,
+  DesktopPlatform,
+  MobilePlatform,
+  Orientation,
+  FileReadType,
+  CapitalizeOptions
+} from '@aegis-framework/artemis';
+
+const config: SpaceConfiguration = {
+  name: 'MyApp',
+  version: '1.0.0'
+};
+
+const storage = new Space(SpaceAdapter.LocalStorage, config);
+```
+
+## License
 
-```
+MIT License - See [LICENSE](LICENSE) for details.