@onetype/framework 2.0.42 → 2.0.43

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({});
-}
-```

package/docs/database.md

@@ -1,171 +0,0 @@
-# Database
-
-Custom ORM built on Knex with a fluent query interface. Supports PostgreSQL with 17+ operators including JSONB.
-
-## Connection
-
-```js
-import database from '#database/load.js';
-import dotenv from 'dotenv';
-
-dotenv.config();
-
-database.Item({
-    id: 'primary',
-    port: 5432,
-    hostname: process.env.DB_HOSTNAME,
-    username: process.env.DB_USERNAME,
-    database: process.env.DB_DATABASE,
-    password: process.env.DB_PASSWORD
-});
-```
-
-Every addon with a `Table()` definition now persists to this database automatically. You can define multiple database connections by using different IDs.
-
-## How it works
-
-The database addon intercepts CRUD middleware channels:
-- `item.crud.create` — `item.Create()`
-- `item.crud.update` — `item.Update()`
-- `item.crud.delete` — `item.Delete()`
-- `addon.items.find` — `addon.Find()`
-
-Without the database addon loaded, the same item API works entirely in-memory. Swap storage without touching business logic.
-
-## Query builder
-
-```js
-// Find one
-const user = await users.Find().filter('id', id).one();
-
-// Find many
-const items = await offers.Find()
-    .filter('deleted', false)
-    .filter('status', 'Aktivna')
-    .sort('score', 'desc')
-    .many();
-
-// Find with specific database connection
-const items = await offers.Find('primary')
-    .filter('organization_id', 9)
-    .many();
-```
-
-## Pagination
-
-```js
-const items = await offers.Find()
-    .page(2)
-    .limit(20)
-    .many();
-
-// Plain result — raw objects with pagination metadata
-const { items, total, pages } = await offers.Find()
-    .page(page)
-    .limit(limit)
-    .plain();
-
-// Count
-const total = await offers.Find()
-    .filter('status', 'Aktivna')
-    .count();
-```
-
-## Filtering
-
-```js
-// Equals (default)
-.filter('status', 'Aktivna')
-
-// Not equals
-.filter('id', excludeId, 'NOT EQUALS')
-
-// IN
-.filter('organization_id', [1, 2, 9], 'IN')
-
-// LIKE / ILIKE (case-insensitive)
-.filter('name', '%beach%', 'ILIKE')
-
-// Comparison
-.filter('age', 18, '>=')
-.filter('age', 65, '<=')
-
-// BETWEEN
-.filter('price', [100, 500], 'BETWEEN')
-
-// NULL / NOT NULL
-.filter('deleted_at', null, 'NULL')
-.filter('email', null, 'NOT NULL')
-
-// PostgreSQL JSONB
-.filter('tags', 'featured', 'CONTAINS')
-.filter('metadata', '{"active": true}', 'CONTAINED')
-.filter('tags', 'premium', 'HAS')
-```
-
-**All operators:** `EQUALS`, `NOT EQUALS`, `IN`, `LIKE`, `ILIKE`, `CONTAINS`, `CONTAINED`, `HAS`, `BETWEEN`, `NULL`, `NOT NULL`, `>`, `>=`, `<`, `<=`, and more.
-
-## Sorting
-
-```js
-.sort('created_at', 'desc')
-.sort('name', 'asc')
-```
-
-## Select
-
-Return only specific fields:
-
-```js
-.select(['id', 'name', 'slug', 'type', 'stars'])
-```
-
-## Joins
-
-```js
-// Join addon by field
-.join('files', 'cover_id', 'cover')
-// → Resolves cover_id into the full file object as 'cover'
-
-// Join addon by array field
-.join('countries', 'countries', 'countries')
-// → Resolves array of country IDs into full country objects
-
-// Join with field selection
-.join('files', 'cover_id', 'cover', ['id', 'hash', 'extension'])
-// → Only include specific fields from the joined items
-
-// Multiple joins
-.join('files', 'cover_id', 'cover')
-.join('files', 'images')
-.join('countries', 'countries', 'countries')
-.join('cities', 'cities', 'cities')
-.join('areas', 'areas', 'areas')
-```
-
-## Offset
-
-```js
-.offset(50)
-```
-
-## Full example
-
-```js
-const offerItems = await offers.Find('primary')
-    .filter('deleted', false)
-    .filter('status', 'Aktivna')
-    .filter('organization_id', [...orgIds, 9], 'IN')
-    .join('countries', 'countries', 'countries')
-    .join('cities', 'cities', 'cities')
-    .join('areas', 'areas', 'areas')
-    .sort('score', 'desc')
-    .select(['id', 'name', 'slug', 'type', 'stars', 'pricing'])
-    .page(1)
-    .limit(12)
-    .many();
-
-offerItems.forEach(offer => {
-    console.log(offer.Get('name'), offer.Get('stars'));
-});
-```