@onetype/framework 2.0.41 → 2.0.43

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.

package/docs/commands.md

@@ -1,308 +0,0 @@
-# Commands
-
-Every API endpoint is a typed, named operation with validated input and output. Commands work over both HTTP and gRPC.
-
-## Defining a command
-
-```js
-import onetype from '#framework/load.js';
-import users from './addon.js';
-
-onetype.AddonReady('commands', (commands) => {
-    commands.Item({
-        id: 'users:create',
-        method: 'POST',
-        endpoint: '/api/users',
-        in: {
-            name: ['string', null, true],
-            email: ['string', null, true],
-            password: ['string', null, true]
-        },
-        out: {
-            user: {
-                type: 'object',
-                config: 'user',
-                required: true
-            }
-        },
-        callback: async function(properties, resolve) {
-            const user = users.Item({
-                name: properties.name,
-                email: properties.email,
-                password: properties.password
-            });
-
-            await user.Create();
-
-            resolve({
-                user: user.Get(['id', 'name', 'email', 'created_at'])
-            });
-        }
-    });
-});
-```
-
-## Command properties
-
-| Property | Description |
-|---|---|
-| `id` | Unique command identifier |
-| `method` | HTTP method: `GET`, `POST`, `PUT`, `DELETE` |
-| `endpoint` | URL pattern, supports `:params` (e.g., `/api/users/:id`) |
-| `exposed` | If `true`, accessible without authentication |
-| `type` | Response type: `'JSON'` (default) or `'HTML'` |
-| `in` | Input schema — validated before callback runs |
-| `out` | Output schema — validated before response is sent |
-| `callback` | `async function(properties, resolve)` |
-
-## Input schema
-
-```js
-in: {
-    // Simple: [type, default, required]
-    name: ['string', null, true],
-    limit: ['number', 20],
-
-    // Complex: object with type + config
-    filters: {
-        type: 'array',
-        each: {
-            type: 'object',
-            config: 'filter'
-        }
-    }
-}
-```
-
-Use `'query'` as shorthand for standard list endpoints:
-
-```js
-in: 'query'  // accepts filters, sort_field, sort_direction, page, limit
-```
-
-## Output schema
-
-```js
-out: {
-    // Reference a DataSchema
-    user: {
-        type: 'object',
-        config: 'user',
-        required: true
-    },
-
-    // Array of schema objects
-    users: {
-        type: 'array',
-        each: {
-            type: 'object',
-            config: 'user'
-        }
-    },
-
-    // Simple fields
-    total: ['number', null, true],
-    page: ['number', null, true]
-}
-```
-
-## Resolve
-
-```js
-// Success
-resolve({ user: userData });
-
-// Error with status code
-resolve(null, 'Not found', 404);
-
-// Streaming (partial response)
-resolve(chunk.data, chunk.message, chunk.code, false);
-// false = don't close the response
-```
-
-## Route params
-
-```js
-commands.Item({
-    id: 'users:get:one',
-    method: 'GET',
-    endpoint: '/api/users/:id',
-    in: {
-        id: ['number', null, true]
-    },
-    callback: async function(properties, resolve) {
-        const user = await users.Find().filter('id', properties.id).one();
-
-        if (!user) return resolve(null, null, 404);
-
-        resolve({
-            user: user.Get(['id', 'name', 'email', 'created_at'])
-        });
-    }
-});
-```
-
-## CRUD pattern
-
-A complete CRUD set for an addon:
-
-**Create:**
-```js
-commands.Item({
-    id: 'tools:create',
-    method: 'POST',
-    endpoint: '/api/tools',
-    in: {
-        name: ['string', null, true],
-        slug: ['string', null, true],
-        description: ['string']
-    },
-    callback: async function(properties, resolve) {
-        const tool = tools.Item({
-            name: properties.name,
-            slug: properties.slug,
-            description: properties.description
-        });
-        await tool.Create();
-        resolve({ tool: tool.Get(['id', 'name', 'slug', 'description', 'created_at']) });
-    }
-});
-```
-
-**Read many:**
-```js
-commands.Item({
-    id: 'tools:get:many',
-    method: 'GET',
-    endpoint: '/api/tools',
-    exposed: true,
-    callback: async function(properties, resolve) {
-        let query = tools.Find().sort('name', 'asc');
-
-        if (properties.filters) {
-            properties.filters.forEach(f => {
-                query = query.filter(f.field, f.value, f.operator || 'EQUALS');
-            });
-        }
-
-        const total = await query.count();
-        const items = await query
-            .page(properties.page || 1)
-            .limit(properties.limit || 10)
-            .many();
-
-        resolve({
-            tools: items.map(item => item.Get(['id', 'name', 'slug', 'description'])),
-            total,
-            page: properties.page || 1,
-            limit: properties.limit || 10
-        });
-    }
-});
-```
-
-**Update:**
-```js
-commands.Item({
-    id: 'tools:update',
-    method: 'PUT',
-    endpoint: '/api/tools/:id',
-    in: { id: ['number', null, true], name: ['string'], description: ['string'] },
-    callback: async function(properties, resolve) {
-        const tool = await tools.Find().filter('id', properties.id).one();
-        if (!tool) return resolve(null, null, 404);
-
-        if (properties.name !== undefined) tool.Set('name', properties.name);
-        if (properties.description !== undefined) tool.Set('description', properties.description);
-        await tool.Update();
-
-        resolve({ tool: tool.Get(['id', 'name', 'description', 'updated_at']) });
-    }
-});
-```
-
-**Delete (soft):**
-```js
-commands.Item({
-    id: 'tools:delete',
-    method: 'DELETE',
-    endpoint: '/api/tools/:id',
-    in: { id: ['number', null, true] },
-    callback: async function(properties, resolve) {
-        const tool = await tools.Find().filter('id', properties.id).one();
-        if (!tool) return resolve(null, null, 404);
-
-        tool.Set('deleted_at', new Date().toISOString());
-        await tool.Update();
-
-        resolve({ tool: tool.Get(['id', 'name', 'deleted_at']) });
-    }
-});
-```
-
-## Dynamic API registration
-
-Register endpoints at runtime when items are added:
-
-```js
-tools.ItemOn('add', function(item) {
-    commands.Item({
-        exposed: true,
-        id: 'tool:' + item.Get('slug'),
-        method: 'POST',
-        endpoint: '/api/run/' + item.Get('slug'),
-        in: item.Get('config_in'),
-        out: item.Get('config_out'),
-        callback: async function(properties, resolve) {
-            // Route to a worker node via gRPC
-            const connections = Object.values(streams.Items()).filter(s =>
-                s.StoreGet('node').Get('tools').includes(item.Get('id'))
-            );
-
-            const stream = connections[Math.floor(Math.random() * connections.length)]
-                .StoreGet('stream');
-            const response = await stream.request(item.Get('slug'), properties);
-            resolve(response.data, response.message, response.code);
-        }
-    });
-});
-```
-
-When a tool is added to the database, an API endpoint appears automatically. Remove the tool, the endpoint disappears.
-
-## HTML commands
-
-Serve HTML responses (for SSR):
-
-```js
-commands.Item({
-    id: 'html',
-    exposed: true,
-    method: 'GET',
-    endpoint: '*',
-    type: 'HTML',
-    callback: async function(properties, resolve) {
-        resolve(html.Fn('render', {
-            head: () => '<title>My App</title>',
-            body: () => '<div id="app"></div>'
-        }));
-    }
-});
-```
-
-## HTTP context
-
-Inside a command callback, access the HTTP request:
-
-```js
-callback: async function(properties, resolve) {
-    const pathname = this.http.url.pathname;
-    const ip = this.http?.user?.ip;
-
-    // Raw response for custom handling
-    this.http.raw.writeHead(301, { 'Location': '/new-url' });
-    this.http.raw.end();
-    this.http.prevent = true;
-    resolve({});
-}
-```