@onetype/framework 2.0.42 → 2.0.43

package/docs/addons.md

@@ -1,281 +0,0 @@
-# Addons
-
-Everything in the framework is an addon. An addon is a typed, persistent entity with fields, items, functions, lifecycle events, and in-memory storage.
-
-## Defining an addon
-
-An addon is defined in an `addon.js` file:
-
-```js
-import onetype from '#framework/load.js';
-
-const users = onetype.Addon('users', (addon) => {
-    addon.Table('users');
-
-    addon.Field('id', ['string']);
-    addon.Field('name', ['string']);
-    addon.Field('email', ['string']);
-    addon.Field('password', ['string']);
-    addon.Field('is_verified', ['boolean']);
-    addon.Field('created_at', ['string']);
-});
-
-export default users;
-```
-
-## Table
-
-`addon.Table(tableName, columnPrefix)` maps the addon to a PostgreSQL table.
-
-```js
-addon.Table('offers', 'offer_');
-```
-
-With prefix `offer_`, field `name` maps to column `offer_name` in the database. Without a prefix, field names match column names directly.
-
-## Fields
-
-`addon.Field(name, [type, default, required])`
-
-```js
-addon.Field('id', ['number|string']);            // union type
-addon.Field('name', ['string', null, true]);     // required
-addon.Field('status', ['string', 'Draft']);       // with default
-addon.Field('tags', ['array']);
-addon.Field('metadata', ['object']);
-addon.Field('active', ['boolean', false]);
-```
-
-**Types:** `string`, `number`, `boolean`, `array`, `object`, `function`, `binary`.
-
-**Union types:** `'number|string'` accepts either type.
-
-Every `Get()` and `Set()` runs through field transform pipelines (`get[]`, `set[]`) then validates against the schema.
-
-## Items
-
-Items are instances of an addon. Full CRUD through middleware chains.
-
-```js
-// Create an item (in-memory)
-const user = users.Item({
-    name: 'Dejan',
-    email: 'hi@iamdejan.com'
-});
-
-// Persist to database
-await user.Create();
-
-// Read fields
-user.Get('name');                                    // single field
-user.Get(['id', 'name', 'email', 'created_at']);     // multiple → plain object
-
-// Update
-user.Set('name', 'Dejan Tomic');
-await user.Update();
-
-// Delete
-await user.Delete();
-
-// Remove from memory (without database delete)
-user.Remove();
-```
-
-### Bulk operations
-
-```js
-// Add multiple items at once
-addon.ItemsAdd(items, null, false);
-
-// Remove all items from memory
-addon.ItemsRemove(false);
-
-// Get all items
-const all = Object.values(addon.Items());
-```
-
-### Get by ID
-
-```js
-const user = users.Item(42);          // get by ID
-const user = users.ItemGet(42);       // same thing
-```
-
-## Functions
-
-Functions are reusable business logic attached to an addon.
-
-```js
-// Define
-users.Fn('password.hash', async function(password) {
-    return await bcrypt.hash(password, 10);
-});
-
-users.Fn('password.verify', async function(password, hash) {
-    return await bcrypt.compare(password, hash);
-});
-
-// Call
-const hash = await users.Fn('password.hash', 'secret123');
-const valid = await users.Fn('password.verify', 'secret123', hash);
-```
-
-Functions can have any number of arguments. Inside the function, `this` gives access to the addon's methods.
-
-## Lifecycle events
-
-React to item operations:
-
-```js
-// When an item is added
-users.ItemOn('add', function(item) {
-    console.log('User added:', item.Get('name'));
-});
-
-// When a field is set
-users.ItemOn('set', async function(item, key, value) {
-    if (key === 'password' && value) {
-        // false = skip callbacks, prevents infinite loop
-        item.Set('password', await users.Fn('password.hash', value), false);
-    }
-});
-
-// When an item is modified (before data changes)
-users.ItemOn('modify', function(item, key, value, prevValue) {
-    console.log(`${key}: ${prevValue} → ${value}`);
-});
-
-// When an item is removed
-users.ItemOn('remove', function(item) {
-    console.log('User removed:', item.Get('id'));
-});
-```
-
-**Available events:** `add`, `added`, `set`, `modify`, `modified`, `remove`, `removed`.
-
-The `callback` parameter on `Set(key, value, callback)` controls whether lifecycle events fire. Pass `false` to skip them — essential when setting values inside a `set` listener to avoid loops.
-
-## AddonReady
-
-Wait for an addon to be loaded before using it:
-
-```js
-onetype.AddonReady('commands', (commands) => {
-    commands.Item({
-        id: 'users:create',
-        method: 'POST',
-        endpoint: '/api/users',
-        // ...
-    });
-});
-```
-
-Import order doesn't matter. `AddonReady` handles async dependency resolution.
-
-## Preloading data
-
-Load database data into memory on startup:
-
-```js
-onetype.AddonReady('organizations', async function(organizations) {
-    await organizations.Find()?.limit(50000).many(true);
-    console.log(`Loaded ${Object.keys(organizations.Items()).length} items`);
-
-    // Optional: periodic refresh
-    setInterval(async () => {
-        const items = await organizations.Find()?.limit(50000).many();
-        organizations.ItemsRemove(false);
-        items.forEach(item => organizations.Item(item.data));
-    }, 600000);
-});
-```
-
-`.many(true)` loads query results into in-memory addon storage.
-
-## Store
-
-Per-item and per-addon in-memory key-value storage:
-
-```js
-// Set
-connection.StoreSet('node', nodeItem);
-connection.StoreSet('stream', streamObject);
-
-// Get
-const node = connection.StoreGet('node');
-const stream = connection.StoreGet('stream');
-```
-
-Useful for attaching runtime state to items without persisting it.
-
-## DataSchema
-
-Register a named schema for use in command `in`/`out` validation:
-
-```js
-onetype.DataSchema('user', {
-    id: ['string'],
-    name: ['string', null, true],
-    email: ['string', null, true],
-    is_verified: ['boolean'],
-    created_at: ['string']
-});
-```
-
-Reference it in commands with `config: 'user'`.
-
-## Addon file structure
-
-Each addon follows this convention:
-
-```
-addons/users/
-    addon.js              Define addon, table, fields
-    load.js               Import addon + commands + functions + events
-    functions/
-        password/
-            hash.js
-            verify.js
-    items/
-        commands/
-            create.js
-            get.many.js
-            get.one.js
-            update.js
-            delete.js
-    item/
-        catch/
-            set.js        Lifecycle hooks
-    events/
-        ready.back.js     Startup logic (preload data, etc.)
-```
-
-The `load.js` file imports everything and is the single entry point:
-
-```js
-import onetype from '#framework/load.js';
-import users from './addon.js';
-
-import './items/commands/create.js';
-import './items/commands/get.many.js';
-import './items/commands/get.one.js';
-import './items/commands/update.js';
-import './items/commands/delete.js';
-
-import './functions/password/hash.js';
-import './functions/password/verify.js';
-
-import './item/catch/set.js';
-
-import './events/ready.back.js';
-
-onetype.DataSchema('user', {
-    id: ['string'],
-    name: ['string', null, true],
-    email: ['string', null, true],
-    is_verified: ['boolean'],
-    created_at: ['string']
-});
-
-export default users;
-```

package/docs/architecture.md

@@ -1,238 +0,0 @@
-# Architecture
-
-## File structure
-
-```
-lib/                     Core OneType class + mixins
-  load.js                Entry point — creates OneType instance, registers all assets, handles signals
-  src/
-    onetype.js           Main class (mixin-composed)
-    mixins/              Addons, Emitter, Middleware, Data, DOM, Route,
-                         Function, Generate, Binaries, Helper, Cookie, Assets, and more
-    classes/
-      addon/             OneTypeAddon + mixins (fields, items, functions, find, render, store)
-        classes/
-          item/          OneTypeAddonItem + mixins (get, set, crud, functions, store)
-          render/        OneTypeAddonRender + mixins (compile, dom, process, events)
-  styles/                Shared CSS (variables, reset, queries, utility classes)
-  items/
-    elements/            Shared UI elements (grouped, IDs are group-prefixed)
-      form/              button, checkbox, field, input, radio, rating, section, slider, textarea
-      global/            card, code, faq, heading, markdown, notice, parameters, tabs, tags
-      sections/          footer, hero, navbar, stats
-      status/            code, empty, error, loading
-    transforms/          Shared transforms
-                         accordion, chart, codeflask, codemirror, comparison,
-                         heatmap, interact, particles, sparkline, swiper, tabs, typed
-
-addons/                  Built-in addon library
-  core/
-    database/            PostgreSQL ORM (Knex, fluent query builder, 17+ operators)
-    servers/             HTTP + gRPC servers
-    clients/             HTTP + gRPC clients
-    commands/            Typed API command system
-    queue/               Concurrency task queue
-    assets/              Convention-based asset bundler (terser)
-  render/
-    directives/          ot-if, ot-for, ot-click, ot-fetch, ot-show, ot-html, ot-text
-    pages/               SPA page router with CSS Grid layouts + async data loading
-    elements/            UI component addon (registration, directives)
-    html/                HTML document builder
-    tags/                HTML tag system
-    transforms/          Transform addon (registration, loading, directives)
-  modules/
-    variables/           Named variable registry
-    actions/             Action triggers
-    events/              Event bindings
-    schedules/           Cron-like scheduling
-    shortcuts/           Keyboard shortcut bindings
-    sources/             Data source registry
-  float/
-    modals/              Modal dialogs
-    toasts/              Toast notifications
-    tooltips/            Tooltip system
-    popups/              Popup menus
-    overlays/            Overlay backdrops
-```
-
-## Application structure
-
-A typical application built on the framework:
-
-```
-my-app/
-  package.json           Import aliases (#framework/*, #database/*, etc.)
-  index.js               Entry point — imports framework, addons, database, servers
-  addons/
-    users/               Application addon
-      addon.js
-      load.js
-      functions/
-      items/commands/
-      item/catch/
-      events/
-  items/
-    database/
-      primary.js         Database connection
-    servers/
-      http.js            HTTP server config
-```
-
-Entry point:
-
-```js
-import onetype from '#framework/load.js';
-import commands from '#commands/load.js';
-import database from '#database/load.js';
-
-import './addons/users/load.js';
-import './addons/offers/load.js';
-
-import './items/database/primary.js';
-import './items/servers/http.js';
-```
-
-## Import aliases
-
-The framework uses Node.js package imports (`#` prefix) defined in `package.json`:
-
-```json
-{
-    "imports": {
-        "#framework/*": "./lib/*",
-        "#database/*": "./addons/core/database/back/*",
-        "#servers/*": "./addons/core/servers/back/*",
-        "#clients/*": "./addons/core/clients/back/*",
-        "#commands/*": "./addons/core/commands/*",
-        "#queue/*": "./addons/core/queue/back/*",
-        "#assets/*": "./addons/core/assets/back/*",
-        "#html/*": "./addons/render/html/*",
-        "#directives/*": "./addons/render/directives/*",
-        "#pages/*": "./addons/render/pages/*",
-        "#elements/*": "./addons/render/elements/*",
-        "#tags/*": "./addons/render/tags/*",
-        "#sources/*": "./addons/modules/sources/*",
-        "#variables/*": "./addons/modules/variables/*"
-    }
-}
-```
-
-## Design decisions
-
-### Mixin composition over inheritance
-
-Both `OneType` and `OneTypeAddon` use `Object.assign(Class.prototype, mixin)`. No class hierarchies, no diamond problems. Each mixin is a plain object of methods merged onto the prototype:
-
-```js
-import AddonItemGet from './mixins/get.js';
-import AddonItemSet from './mixins/set.js';
-import AddonItemCrud from './mixins/crud.js';
-
-Object.assign(OneTypeAddonItem.prototype, AddonItemGet);
-Object.assign(OneTypeAddonItem.prototype, AddonItemSet);
-Object.assign(OneTypeAddonItem.prototype, AddonItemCrud);
-```
-
-### Middleware as the extension point
-
-CRUD operations and queries are middleware chains:
-- `item.crud.create` — intercepted by database addon for INSERT
-- `item.crud.update` — intercepted for UPDATE
-- `item.crud.delete` — intercepted for DELETE
-- `addon.items.find` — intercepted for SELECT
-
-Without the database addon, everything works in-memory. Swap storage without touching business logic.
-
-### Self-registering imports
-
-Importing an addon's `load.js` registers it with the framework. No manual wiring, no dependency injection container, no configuration object. `AddonReady` handles async dependency resolution — import order doesn't matter.
-
-### Field transforms
-
-Every field has `get[]` and `set[]` arrays of transform functions plus a `define` schema:
-
-```
-Set('name', value)
-  → run set[] transforms
-  → validate against define schema
-  → fire lifecycle callbacks
-  → store in item.data
-```
-
-Computed fields, type coercion, and normalization are declared at the field level.
-
-### Proxy-driven reactivity
-
-Render components return a `Proxy`. Setting a property schedules a debounced `Update()`:
-
-```
-this.count++
-  → Proxy trap
-  → schedule Update() (16ms debounce)
-  → re-compile template
-  → DOM diff
-  → patch changes
-```
-
-Batched updates, no virtual DOM overhead.
-
-### Binary transport over gRPC
-
-gRPC messages are JSON strings. Buffers can't be embedded directly. The framework extracts all Buffer instances into a separate `map<string, bytes>` field before sending:
-
-```
-Send: { data: { file: <Buffer> } }
-  → extract: { data: { file: "$$bin_0" }, binaries: { "$$bin_0": <Buffer> } }
-  → send JSON + binaries separately
-
-Receive:
-  → inject: { data: { file: <Buffer> } }
-```
-
-Transparent binary transport over the same stream.
-
-### Centralized asset registry
-
-All asset paths are registered centrally in `lib/load.js` via `onetype.Assets(id, url, config)`. This decouples asset path knowledge from individual addons — the framework controls what gets bundled, regardless of whether a backend addon is loaded.
-
-```js
-// lib/load.js — top-level registrations
-onetype.Assets('framework', import.meta.url, { js: { path: '.', exclude: ['load.js', 'items', 'styles'] } });
-onetype.Assets('styles', import.meta.url, { css: 'styles' });
-onetype.Assets('commands', import.meta.url, { js: { path: '../addons/core/commands', exclude: ['../addons/core/commands/back'] } });
-```
-
-Shared elements and transforms use `onetype.AddonReady` to register only after their parent addon is loaded. The JS files themselves contain the wrapper:
-
-```js
-// lib/items/elements/form/button/button.js
-onetype.AddonReady('elements', (elements) =>
-{
-    elements.ItemAdd({ id: 'form-button', ... });
-});
-
-// lib/items/transforms/swiper/swiper.js
-onetype.AddonReady('transforms', (transforms) =>
-{
-    transforms.ItemAdd({ id: 'swiper', ... });
-});
-```
-
-Element IDs are group-prefixed: `form-button`, `global-card`, `sections-navbar`, `status-loading`. HTML tags follow the same pattern: `<e-form-button>`, `<e-global-card>`, `<e-status-loading>`.
-
-The import function reads from the registry to resolve paths:
-
-```js
-assets.Fn('import', ['framework', 'styles', 'commands', 'elements/form/input', 'transforms/swiper']);
-```
-
-### Convention-based bundling
-
-No webpack, no build configuration. The asset bundler:
-1. Scans directories recursively
-2. Prioritizes `addon.js` files
-3. Strips `import`/`export` statements
-4. Concatenates by priority order
-5. Minifies via terser
-
-ES module source files become a browser-loadable bundle.