@nuxodin/item 0.6.4

package/tools/AsyncChild.js

@@ -0,0 +1,44 @@
+import { Item } from "../item.js";
+
+/*
+AsyncChild is useful when you have a data source that only supports object replace
+but not partial updates.
+This item will then read the full parent object, update the child value and write the full object back.
+
+Note: io regions do the write-through by themselves now (`owner.readsFull = true` + plain
+Items as children). What remains here is the auto-read — the core throws on an unloaded
+region instead. See doc/PLAN-io-regions.md: this class may be dropped entirely.
+*/
+
+export class AsyncChild extends Item {
+    // reader delivers (via ioRoot) this child's whole subtree — licences partial writes once loaded
+    readsFull = true;
+
+    constructor(parent, key) {
+        super(parent, key);
+        this.ioRoot = parent instanceof AsyncChild ? parent.ioRoot : parent;
+    }
+
+    async reader() {
+        await this.ioRoot.read();
+    }
+
+    async writer(value) { // the source only supports full replace, so write the whole root region
+        // `loaded`, not `filled`: navigating to a child already fills the tree, only io knows
+        // whether the root's data ever actually arrived — writing an unread region would erase it.
+        if (this.ioRoot.reader && !this.ioRoot.loaded) {
+            await this.ioRoot.read();
+            this.set(value, { local: true }); // the read overwrote the fresh local change — re-apply
+        }
+        return this.ioRoot.io.set(this.ioRoot.peek());
+    }
+
+    async remover() {
+        await this.parent.read();
+        const data = this.parent.peek();
+        if (data) {
+            delete data[this.key];
+            await this.parent.set(structuredClone(data));
+        }
+    }
+}

package/tools/access.js

@@ -0,0 +1,36 @@
+/*
+Usage:
+import { canRead, canWrite } from './access.js';
+import { resolveVariables } from './condition.js';
+const resolvedSchema = resolveVariables(rawSchema, { $user: currentUser });
+// schema auf root-item setzen...
+await canRead(ticketItem);   // true/false
+await canWrite(ticketItem);  // true/false
+*/
+import { evaluate, resolveVariables } from './condition.js';
+import { resolveDataRef } from './schema/utils.js';
+
+export { resolveVariables }; // re-export für Convenience
+
+async function onUnknownOperator(condition, obj, item) {
+    if (condition[0] === 'cascade') {
+        const fieldItem = item.item(condition[1]);
+        const { refItem } = await resolveDataRef(fieldItem) ?? {};
+        return refItem ? canRead(refItem) : false;
+    }
+    return false;
+}
+
+async function check(condition, item) {
+    return evaluate(condition, item.get(), (cond, obj) => onUnknownOperator(cond, obj, item));
+}
+
+export async function canRead(item) {
+    const schema = item.schema?.additionalProperties ?? item.schema;
+    return await check(schema?.['x-readable'], item) || await check(schema?.['x-writable'], item);
+}
+
+export async function canWrite(item) {
+    const schema = item.schema?.additionalProperties ?? item.schema;
+    return check(schema?.['x-writable'], item);
+}

package/tools/beta/collectChanges.js

@@ -0,0 +1,88 @@
+
+const removedSymbol = Symbol('removed');
+
+// An other variant would be to use structuralClone to clone the object and then compare it with the original
+// This would probably use more memory on big objects but would be simpler, worth it?
+
+export function collectChanges(rootItem, onchange) {
+    // items can be removed and then added again
+    // so on remove we add a symbol to mark it as removed than can be overwritten by a new value
+
+    // we need a wrapper to be able to have a reference even if the root value is not an object
+    let wrapper = {};
+
+    const startPathLevel = rootItem.path.length;
+
+    rootItem.addEventListener('changeIn', event => {
+        const {target, value, remove, add} = event;
+        if (add) return; // will be handled if the value is set (an other changeIn event)
+
+        const relativePath = target.path.slice(startPathLevel);
+        const path = ['changes', ...relativePath];
+        const last = path.pop();
+
+        let current = wrapper;
+        for (const key of path) {
+            if (!isObject(current[key])) current[key] = {};
+            current = current[key];
+        }
+        if (remove) {
+            current[last] ??= {};
+            current[last][remove.key] = removedSymbol;
+        } else {
+            current[last] = value ?? null;
+        }
+        onchange && onchange();
+    });
+    return {
+        getAndReset() {
+            const changes = wrapper.changes;
+            wrapper = {};
+
+            const deletions = {};
+            splitDeletions(changes, deletions);
+
+            return {changes, deletions};
+        },
+    }
+}
+
+function splitDeletions(obj, deletions){
+    for (const key in obj) {
+        if (obj[key] === removedSymbol) {
+            deletions[key] = true;
+            delete obj[key];
+        } else if (isObject(obj[key])) {
+            deletions[key] = {};
+            splitDeletions(obj[key], deletions[key]);
+            if (Object.keys(obj[key]).length === 0) delete obj[key];
+            if (Object.keys(deletions[key]).length === 0) delete deletions[key];
+        }
+    }
+}
+
+
+// patch
+export function patch(item, {changes, deletions}) {
+    patchChanges(item, changes);
+    patchDeletions(item, deletions);
+}
+function patchChanges(item, changes) {
+    if (changes === undefined) return;
+    if (!isObject(changes)) {
+        item.value = changes;
+    } else {
+        for (const key in changes) {
+            patchChanges(item.item(key), changes[key]);
+        }
+    }
+}
+function patchDeletions(item, deletions) {
+    for (const key in deletions) {
+        if (deletions[key] === true) item.item(key).remove();
+        else if (isObject(deletions[key])) patchDeletions(item.item(key), deletions[key]);
+        else console.error('true or {}', deletions[key])
+    }
+}
+
+const isObject = value => typeof value === 'object' && value !== null;

package/tools/beta/syncWith.js

@@ -0,0 +1,22 @@
+// beta, subject to change or deleted
+
+export function syncWith(rootItem, object={}) {
+    rootItem.addEventListener('changeIn', event => {
+        if (!('value' in event)) return;
+        const keys = [...event.target.path];
+        const lastKey = keys.pop();
+        let current = object;
+        keys.forEach(key => {
+            if (!isObject(current[key])) {
+                current[key] = Object.create(null);
+            }
+            current = current[key];
+        });
+        current[lastKey] = event.target.value;
+    });
+    return object;
+}
+
+function isObject(obj) {
+    return obj === Object(obj);
+}

package/tools/condition.js

@@ -0,0 +1,65 @@
+
+const operators = {
+    'eq':         (a, b) => a === b,
+    'ne':         (a, b) => a !== b,
+    'gt':         (a, b) => a >   b,
+    'gte':        (a, b) => a >=  b,
+    'lt':         (a, b) => a <   b,
+    'lte':        (a, b) => a <=  b,
+    'in':         (a, b) => b.includes(a),
+    'nin':        (a, b) => !b.includes(a),
+    'exists':     (a, b) => (a !== undefined) === b,
+    'includes':   (a, b) => String(a).includes(b),
+    'startsWith': (a, b) => String(a).startsWith(b),
+    'endsWith':   (a, b) => String(a).endsWith(b),
+    'regex':      (a, b) => new RegExp(b).test(String(a)),
+};
+
+export function resolveVariables(condition, vars) {
+    if (typeof condition === 'string') {
+        if (!condition.startsWith('$')) return condition;
+        const path = condition.slice(1).split('.');
+        return path.reduce((obj, key) => obj?.[key], vars) ?? condition;
+    }
+    if (Array.isArray(condition)) return condition.map(c => resolveVariables(c, vars));
+    if (condition && typeof condition === 'object') {
+        return Object.fromEntries(
+            Object.entries(condition).map(([k, v]) => [k, resolveVariables(v, vars)])
+        );
+    }
+    return condition;
+}
+
+export function matchesCondition(fieldVal, condition, obj) {
+    if (!Array.isArray(condition)) return fieldVal === condition; // shorthand eq
+    const [op, expected] = condition;
+    const resolved = (Array.isArray(expected) && expected[0] === 'ref')
+        ? obj[expected[1]]
+        : expected;
+    return operators[op]?.(fieldVal, resolved) ?? false;
+}
+
+// obj → AND über Felder, Array → OR über Einträge
+// onUnknownOperator(condition, obj) → bool — für eigene Operatoren (z.B. cascade)
+export function evaluate(condition, obj, onUnknownOperator) {
+    if (condition === true || condition === false) return condition;
+    if (condition == null) return false;
+
+    if (Array.isArray(condition)) {
+        const [op] = condition;
+        if (typeof op === 'string' && !(op in operators) && op !== 'ref') {
+            return onUnknownOperator?.(condition, obj) ?? false;
+        }
+        // Array → OR
+        return condition.some(c => evaluate(c, obj, onUnknownOperator));
+    }
+
+    // Object → AND
+    if (typeof condition === 'object' && typeof obj === 'object') {
+        return Object.entries(condition).every(([key, cond]) =>
+            matchesCondition(obj[key], cond, obj)
+        );
+    }
+
+    return false;
+}

package/tools/csvDataItem.js

@@ -0,0 +1,139 @@
+import { item } from '../item.js';
+
+/**
+ * Bidirectional sync between Item and CSV format
+ * Lightweight CSV parser/stringifier (no dependencies)
+ * Similar to jsonDataItem but for CSV files
+ * 
+ * Features:
+ * - Auto-sync Item → CSV (debounced)
+ * - Auto-sync CSV file → Item (on file change)
+ * - Headers from first row
+ * - Array of objects structure
+ */
+export async function csvDataItem(csvItem, options = {}) {
+    const {
+        delimiter = ',',
+        columns = null, // auto-detect if null
+        keyColumn = null, // if set, use this column as item key
+    } = options;
+
+    const root = item();
+
+    // Parse CSV string to array of objects
+    const parseCsv = (csv) => {
+        if (!csv || !csv.trim()) return [];
+        
+        const lines = csv.trim().split(/\r?\n/);
+        if (lines.length === 0) return [];
+        
+        // Parse a single line respecting quotes
+        const parseLine = (line) => {
+            const result = [];
+            let current = '';
+            let inQuotes = false;
+            
+            for (let i = 0; i < line.length; i++) {
+                const char = line[i];
+                const nextChar = line[i + 1];
+                
+                if (char === '"') {
+                    if (inQuotes && nextChar === '"') {
+                        current += '"';
+                        i++; // Skip next quote
+                    } else {
+                        inQuotes = !inQuotes;
+                    }
+                } else if (char === delimiter && !inQuotes) {
+                    result.push(current);
+                    current = '';
+                } else {
+                    current += char;
+                }
+            }
+            result.push(current);
+            return result;
+        };
+        
+        // Get headers
+        const csvHeaders = columns || parseLine(lines[0]).map(h => h.trim());
+        const dataStart = columns ? 0 : 1;
+        
+        // Parse data rows
+        return lines.slice(dataStart).map((line, index) => {
+            const values = parseLine(line);
+            const row = {};
+            csvHeaders.forEach((h, i) => {
+                row[h] = values[i] ?? '';
+            });
+            return row;
+        });
+    };
+
+    // Convert array of objects to CSV string
+    const stringifyCsv = (data) => {
+        if (!Array.isArray(data) || data.length === 0) {
+            return columns ? columns.join(delimiter) + '\n' : '';
+        }
+        
+        const cols = columns || Object.keys(data[0]);
+        
+        // Escape values containing delimiter, quotes, or newlines
+        const escapeValue = (val) => {
+            const str = String(val ?? '');
+            if (str.includes(delimiter) || str.includes('"') || str.includes('\n')) {
+                return '"' + str.replace(/"/g, '""') + '"';
+            }
+            return str;
+        };
+        
+        const lines = [
+            cols.join(delimiter),
+            ...data.map(row => cols.map(c => escapeValue(row[c])).join(delimiter))
+        ];
+        
+        return lines.join('\n');
+    };
+
+    // Sync from CSV to Item
+    const syncFromCsv = (csv) => {
+        const data = parseCsv(csv);
+        
+        // Clear existing
+        for (const child of [...root.items()]) child.remove();
+        
+        // Set new data
+        data.forEach((row, index) => {
+            const key = keyColumn ? row[keyColumn] : String(index);
+            if (key !== undefined && key !== null) {
+                root.item(String(key)).set(row);
+            }
+        });
+    };
+
+    // Sync from Item to CSV
+    const syncToCsv = () => {
+        const data = [...root.items()].map(child => child.value);
+        const csv = stringifyCsv(data);
+        csvItem.set(csv);
+    };
+
+    // Initial sync
+    syncFromCsv(await csvItem.read());
+
+    // Item → CSV (debounced)
+    root.addEventListener('changeIn', debounce(syncToCsv, 100));
+
+    // CSV → Item (on external change)
+    csvItem.addEventListener('change', () => syncFromCsv(csvItem.value));
+
+    return root;
+}
+
+function debounce(fn, ms) {
+    let timer;
+    return (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), ms);
+    };
+}

package/tools/db/connect.js

@@ -0,0 +1,27 @@
+// Bind a dialect descriptor + an injected runner into a small query handle.
+// The runner ({ query, exec, transaction }) is connection-aware but dialect-dumb;
+// tools/db never imports a database client. Everything speaks only sql`` fragments.
+import { render, resolveSql } from './sql.js';
+
+/** @param dialect descriptor  @param runner { query(text,params), exec(text,params), transaction(fn) } */
+export function connect(dialect, runner) {
+    const query = async (frag) => {
+        await resolveSql(frag);
+        const { text, params } = render(frag, dialect);
+        return runner.query(text, params);
+    };
+    const exec = async (frag, { returning } = {}) => {
+        if (returning && dialect.appendReturning) frag = dialect.appendReturning(frag, returning);
+        await resolveSql(frag);
+        const { text, params } = render(frag, dialect);
+        return runner.exec(text, params);
+    };
+    return {
+        dialect,
+        query,
+        exec,
+        row: (frag) => query(frag).then((rows) => rows[0]),
+        columns: (table) => dialect.columns(runner.query, table),
+        transaction: (fn) => runner.transaction(fn),
+    };
+}

package/tools/db/dialect/mysql.js

@@ -0,0 +1,12 @@
+// MySQL dialect descriptor — pure SQL knowledge, no connection.
+import { schemaFromDb } from '../../schema/db/mysql/from-db.js';
+import { makeColumns } from '../shared.js';
+
+export const mysql = {
+    name: 'mysql',
+    quoteId: (name) => `\`${String(name).replaceAll('`', '``')}\``,
+    placeholder: () => '?',
+    emptyInsert: '() VALUES ()',
+    insertId: 'lastId',
+    columns: makeColumns(schemaFromDb),
+};

package/tools/db/dialect/pg.js

@@ -0,0 +1,15 @@
+// PostgreSQL dialect descriptor — pure SQL knowledge, no connection.
+import { schemaFromDb } from '../../schema/db/pg/from-db.js';
+import { makeColumns } from '../shared.js';
+import { sql } from '../sql.js';
+
+export const pg = {
+    name: 'postgres',
+    quoteId: (name) => `"${String(name).replaceAll('"', '""')}"`,
+    placeholder: (n) => '$' + n,
+    emptyInsert: 'DEFAULT VALUES',
+    insertId: 'returning',
+    // pg has no lastInsertId; the id comes back via RETURNING (used by connect.exec).
+    appendReturning: (frag, col) => sql`${frag} RETURNING ${sql.id(col)}`,
+    columns: makeColumns(schemaFromDb),
+};

package/tools/db/dialect/sqlite.js

@@ -0,0 +1,12 @@
+// SQLite dialect descriptor — pure SQL knowledge, no connection.
+import { schemaFromDb } from '../../schema/db/sqlite/from-db.js';
+import { makeColumns } from '../shared.js';
+
+export const sqlite = {
+    name: 'sqlite',
+    quoteId: (name) => `"${String(name).replaceAll('"', '""')}"`,
+    placeholder: () => '?',
+    emptyInsert: 'DEFAULT VALUES',
+    insertId: 'lastId',
+    columns: makeColumns(schemaFromDb),
+};

package/tools/db/shared.js

@@ -0,0 +1,7 @@
+// Helpers shared across dialect descriptors.
+
+/** Build a `columns(query, table)` that delegates introspection to a schema from-db. */
+export const makeColumns = (schemaFromDb) => async (query, table) => {
+    const schema = await schemaFromDb(query);
+    return schema.properties[table]?.additionalProperties?.properties ?? {};
+};

package/tools/db/sql.d.ts

@@ -0,0 +1,24 @@
+export type SqlPart = { text: string } | { param: unknown } | { id: unknown };
+
+export class Sql {
+    parts: SqlPart[];
+    constructor(parts?: SqlPart[]);
+}
+
+export interface SqlTag {
+    (strings: TemplateStringsArray, ...values: unknown[]): Sql;
+    id(name: string | { toString(): string } | Promise<string | { toString(): string }>): Sql;
+    raw(text: string): Sql;
+    join(frags: Sql[], separator?: string): Sql;
+}
+
+export const sql: SqlTag;
+
+export function resolveSql(frag: Sql): Promise<void>;
+
+export function render(
+    frag: Sql,
+    dialect: { quoteId(name: string): string; placeholder(n: number): string },
+): { text: string; params: unknown[] };
+
+export function isTemplate(a: unknown): a is TemplateStringsArray;

package/tools/db/sql.js

@@ -0,0 +1,83 @@
+// @ts-self-types="./sql.d.ts"
+// Dialect-neutral SQL fragments. Build with the sql`` tag — interpolated values
+// become bound params, nested fragments/ids compose. A driver renders the AST to
+// its dialect (placeholder + identifier quoting) at execution time. Pure data, no dialect.
+
+export class Sql {
+    /** @param {Array<{text:string}|{param:unknown}|{id:string}>} parts */
+    constructor(parts = []) { this.parts = parts; }
+}
+
+/** Tagged template; interpolated values become bound params, nested Sql composes. */
+export function sql(strings, ...values) {
+    const parts = [];
+    strings.forEach((s, i) => {
+        if (s) parts.push({ text: s });
+        if (i < values.length) {
+            const v = values[i];
+            if (v instanceof Sql) parts.push(...v.parts);
+            else parts.push({ param: v });
+        }
+    });
+    return new Sql(parts);
+}
+
+/** Quote a dynamic identifier (table/column) per dialect. */
+sql.id = (name) => new Sql([{ id: name }]);
+
+/** Inject text verbatim — escape hatch, never pass user input. */
+sql.raw = (text) => new Sql([{ text }]);
+
+/** Join fragments with a separator (IN-lists, column sets). */
+sql.join = (frags, separator = ', ') => {
+    const parts = [];
+    frags.forEach((f, i) => {
+        if (i) parts.push({ text: separator });
+        parts.push(...f.parts);
+    });
+    return new Sql(parts);
+};
+
+// Objects with their own toString bind as strings; plain objects/arrays are
+// mistakes (drivers would mangle them, e.g. mysql2's `key`='value' expansion).
+function toParam(v) {
+    if (v === null || typeof v !== 'object' || v instanceof Date || v instanceof Uint8Array) return v;
+    if (Array.isArray(v) || v.toString === Object.prototype.toString) {
+        throw new TypeError('sql: cannot bind ' + (Array.isArray(v) ? 'an array' : 'a plain object') + ' as parameter');
+    }
+    return String(v);
+}
+
+// Lower an AST to { text, params } for a dialect. Stays dialect-agnostic: the
+// dialect (quoteId + placeholder) is passed in, never imported here.
+/** @param {Sql} frag  @param {{quoteId(name:string):string, placeholder(n:number):string}} dialect */
+export function render(frag, dialect) {
+    let text = '';
+    const params = [];
+    for (const part of frag.parts) {
+        if ('text' in part) text += part.text;
+        else if ('id' in part) text += dialect.quoteId(String(part.id));
+        else { params.push(toParam(part.param)); text += dialect.placeholder(params.length); }
+    }
+    return { text, params };
+}
+
+/** Await promised params/ids in place, in parallel; a promise resolving to a
+ * Sql fragment composes. Run by the query layer before render. */
+export async function resolveSql(frag) {
+    if (!frag.parts.some(p => p.param instanceof Promise || p.id instanceof Promise)) return;
+    frag.parts = (await Promise.all(frag.parts.map(async p => {
+        if (p.id instanceof Promise) return [{ id: await p.id }];
+        if (!(p.param instanceof Promise)) return [p];
+        const v = await p.param;
+        if (v instanceof Sql) { await resolveSql(v); return v.parts; }
+        return [{ param: v }];
+    }))).flat();
+}
+
+// Companion to the sql`` tag: lets a query API accept either a tagged template
+// or a pre-built Sql fragment, and dispatch on which it got.
+/** True for a tagged-template call (first arg is the template strings array). */
+export function isTemplate(a) {
+    return Array.isArray(a?.raw);
+}

package/tools/httpRouter.js

@@ -0,0 +1,66 @@
+/**
+ * HTTP router for Item structures
+ * REST API: GET/POST/PUT/PATCH/DELETE/OPTIONS
+ */
+
+/**
+ * Creates a router handler that responds to HTTP requests for Item access
+ * @param {Item} rootItem - The root Item instance to expose
+ * @param {string} [basePath=''] - Base path to listen on (e.g. '/api')
+ * @returns {Function} Async handler (request) => Response
+ */
+export function createItemRouter(rootItem, basePath = '') {
+    const prefixParts = basePath.replace(/^\/|\/$/g, '').split('/').filter(Boolean);
+
+    const methods = {
+        async GET({ path, url }) {
+            const item = rootItem.sub(path);
+            if (url.searchParams.has('$schema')) return jsonResponse(item.schema ?? null);
+            const query = url.searchParams.has('q') ? JSON.parse(url.searchParams.get('q')) : null;
+            await item.read(query);
+            const value = item.get({ depth: query?.depth ?? 1 });
+            return jsonResponse({value, depth: query?.depth ?? 1});
+        },
+        async PUT({ path, request }) {
+            await rootItem.sub(path).set(await request.json());
+            return jsonResponse({ success: true });
+        },
+        async PATCH({ path, request }) {
+            await rootItem.sub(path).patch(await request.json());
+            return jsonResponse({ success: true });
+        },
+        async DELETE({ path }) {
+            await rootItem.has(path)?.remove();
+            return new Response(null, { status: 204 });
+        },
+        async POST({ path, request }) {
+            const newItem = await rootItem.sub(path).add(await request.json());
+            return jsonResponse({ success: true, key: newItem.key });
+        },
+        async OPTIONS() {
+            const headers = new Headers({'Access-Control-Max-Age': '86400'});
+            return new Response(null, { status: 204, headers });
+        },
+    };
+
+    return async (request) => {
+        try {
+            const url = new URL(request.url);
+            const segments = url.pathname.split('/').filter(Boolean);
+            if (prefixParts.some((p, i) => segments[i] !== p)) return null;
+            const path = segments.slice(prefixParts.length);
+            const handler = methods[request.method];
+            if (!handler) return jsonResponse({ error: 'Method not allowed' }, 405);
+            return await handler({ path, request, url });
+        } catch (err) {
+            return jsonResponse({ error: err.message }, 400);
+        }
+    };
+}
+
+function jsonResponse(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}

package/tools/jsonDataItem.js

@@ -0,0 +1,29 @@
+import { item } from '../item.js';
+
+export async function jsonDataItem(jsonItem) {
+    const root = item();
+    const syncFromJson = (json) => root.set(json ? JSON.parse(json) : null);    
+    const syncToJson = () => jsonItem.set(JSON.stringify(root.value, null, 2));
+    await jsonItem.read();
+    syncFromJson(jsonItem.get());
+    root.addEventListener('changeIn', debounce(syncToJson, 25));
+    jsonItem.addEventListener('change', () => syncFromJson(jsonItem.value));
+    return root;
+}
+
+/** JSON-backed root item: every write in the tree persists the whole document.
+ *  `set()`/`patch()` return a promise — await it when the write must have landed. */
+export function bildJsonItem(raw, save, options = {}) {
+    const root = item(JSON.parse(raw || "{}"));
+    root.writer = v => save(JSON.stringify(v));
+    root.io.options.debounceMs = options.debounce ?? 25;
+    return root;
+}
+
+function debounce(fn, ms) {
+    let timer;
+    return (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), ms);
+    };
+}