@treenity/core 1.0.48 → 3.0.0

package/src/contexts/service/index.test.ts

@@ -0,0 +1,323 @@
+import { createNode, register } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { withSubscriptions } from '#server/sub';
+import { createMemoryTree, resolveRef } from '#tree';
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { type ServiceCtx, type ServiceHandle, startServices, type StoreEvent } from './index';
+
+describe('resolveRef', () => {
+  it('returns node as-is when not a ref', async () => {
+    const store = createMemoryTree();
+    const node = createNode('/a', 'dir');
+    await store.set(node);
+    assert.deepEqual(await resolveRef(store, node), node);
+  });
+
+  it('resolves ref to target node', async () => {
+    const store = createMemoryTree();
+    const target = createNode('/bot', 'bot');
+    await store.set(target);
+    const refNode = { $path: '/sys/autostart/bot', $type: 'ref', $ref: '/bot' } as any;
+    await store.set(refNode);
+    assert.deepEqual(await resolveRef(store, refNode), target);
+  });
+
+  it('throws on broken ref', async () => {
+    const store = createMemoryTree();
+    const refNode = { $path: '/sys/autostart/x', $type: 'ref', $ref: '/missing' } as any;
+    await assert.rejects(() => resolveRef(store, refNode));
+  });
+});
+
+describe('startServices', () => {
+  beforeEach(() => clearRegistry());
+
+  it('returns null when no autostart node', async () => {
+    const store = createMemoryTree();
+    assert.equal(await startServices(store, () => () => {}), null);
+  });
+
+  it('starts autostart service', async () => {
+    let started = false,
+      stopped = false;
+    register('autostart', 'service', async () => {
+      started = true;
+      return {
+        stop: async () => {
+          stopped = true;
+        },
+      };
+    });
+
+    const store = createMemoryTree();
+    await store.set(createNode('/sys/autostart', 'autostart'));
+    const handle = await startServices(store, () => () => {});
+
+    assert.equal(started, true);
+    assert.ok(handle);
+    await handle.stop();
+    assert.equal(stopped, true);
+  });
+
+  it('autostart walks children and starts services', async () => {
+    const log: string[] = [];
+
+    register('autostart', 'service', async (node, ctx) => {
+      const { items } = await ctx.store.getChildren(node.$path);
+      const handles: ServiceHandle[] = [];
+      for (const child of items) {
+        const target = await resolveRef(ctx.store, child);
+        const { resolve } = await import('#core');
+        const handler = resolve(target.$type, 'service');
+        if (!handler) continue;
+        try {
+          handles.push(await handler(target, ctx));
+        } catch {}
+      }
+      return {
+        stop: async () => {
+          for (const h of handles) await h.stop();
+        },
+      };
+    });
+
+    register('echo', 'service', async (node) => {
+      log.push(`start:${node.$path}`);
+      return {
+        stop: async () => {
+          log.push(`stop:${node.$path}`);
+        },
+      };
+    });
+
+    const store = createMemoryTree();
+    await store.set(createNode('/sys/autostart', 'autostart'));
+    await store.set(createNode('/sys/autostart/a', 'echo'));
+    const target = createNode('/srv/b', 'echo');
+    await store.set(target);
+    await store.set({ $path: '/sys/autostart/b', $type: 'ref', $ref: '/srv/b' } as any);
+
+    const handle = await startServices(store, () => () => {})!;
+    assert.deepEqual(log, ['start:/sys/autostart/a', 'start:/srv/b']);
+
+    await handle!.stop();
+    assert.deepEqual(log, [
+      'start:/sys/autostart/a',
+      'start:/srv/b',
+      'stop:/sys/autostart/a',
+      'stop:/srv/b',
+    ]);
+  });
+
+  it('continues when one service fails to start', async () => {
+    const log: string[] = [];
+
+    register('autostart', 'service', async (node, ctx) => {
+      const { items } = await ctx.store.getChildren(node.$path);
+      const handles: ServiceHandle[] = [];
+      for (const child of items) {
+        const target = await resolveRef(ctx.store, child);
+        const { resolve } = await import('#core');
+        const handler = resolve(target.$type, 'service');
+        if (!handler) continue;
+        try {
+          handles.push(await handler(target, ctx));
+        } catch (e) {
+          /* swallow */
+        }
+      }
+      return {
+        stop: async () => {
+          for (const h of handles) await h.stop();
+        },
+      };
+    });
+
+    register('bad', 'service', async () => {
+      throw new Error('boom');
+    });
+    register('good', 'service', async (node) => {
+      log.push('started');
+      return {
+        stop: async () => {
+          log.push('stopped');
+        },
+      };
+    });
+
+    const store = createMemoryTree();
+    await store.set(createNode('/sys/autostart', 'autostart'));
+    await store.set(createNode('/sys/autostart/a', 'bad'));
+    await store.set(createNode('/sys/autostart/b', 'good'));
+
+    const handle = await startServices(store, () => () => {});
+    assert.deepEqual(log, ['started']);
+    await handle!.stop();
+    assert.deepEqual(log, ['started', 'stopped']);
+  });
+});
+
+describe('ServiceCtx.subscribe', () => {
+  beforeEach(() => clearRegistry());
+
+  it('service receives subscribe in ctx', async () => {
+    let receivedSubscribe = false;
+    register('watcher', 'service', async (_node, ctx) => {
+      receivedSubscribe = typeof ctx.subscribe === 'function';
+      return { stop: async () => {} };
+    });
+
+    const store = createMemoryTree();
+    await store.set(createNode('/sys/autostart', 'watcher'));
+    await startServices(store, () => () => {});
+    assert.equal(receivedSubscribe, true);
+  });
+
+  it('subscribe fires on set', async () => {
+    const events: StoreEvent[] = [];
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); });
+
+    const unsub = subscribe('/config/bot', (e) => events.push(e));
+
+    await reactive.set(createNode('/config/bot', 'dir'));
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'set');
+    assert.equal(events[0].path, '/config/bot');
+
+    unsub();
+    await reactive.set({ ...createNode('/config/bot', 'dir'), name: 'changed' });
+    assert.equal(events.length, 1, 'no events after unsub');
+  });
+
+  it('subscribe fires on remove', async () => {
+    const events: StoreEvent[] = [];
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); });
+
+    await reactive.set(createNode('/config/bot', 'dir'));
+    subscribe('/config/bot', (e) => events.push(e));
+
+    await reactive.remove('/config/bot');
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'remove');
+    assert.equal(events[0].path, '/config/bot');
+  });
+
+  it('subscribe fires patch on update', async () => {
+    const events: StoreEvent[] = [];
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); });
+
+    await reactive.set(createNode('/config/bot', 'dir'));
+    subscribe('/config/bot', (e) => events.push(e));
+
+    await reactive.set({ ...createNode('/config/bot', 'dir'), token: 'abc', $rev: 1 });
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'patch');
+    assert.equal(events[0].path, '/config/bot');
+  });
+
+  it('prefix subscribe catches children', async () => {
+    const events: StoreEvent[] = [];
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb, opts) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); }, opts);
+
+    subscribe('/config', (e) => events.push(e), { children: true });
+
+    await reactive.set(createNode('/config/bot', 'dir'));
+    await reactive.set(createNode('/config/db', 'dir'));
+    assert.equal(events.length, 2);
+    assert.equal(events[0].path, '/config/bot');
+    assert.equal(events[1].path, '/config/db');
+  });
+
+  it('exact subscribe does NOT catch children', async () => {
+    const events: StoreEvent[] = [];
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb, opts) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); }, opts);
+
+    subscribe('/config', (e) => events.push(e));
+
+    await reactive.set(createNode('/config/bot', 'dir'));
+    assert.equal(events.length, 0, 'exact subscribe should not catch children');
+  });
+
+  it('does not fire for unrelated paths', async () => {
+    const events: StoreEvent[] = [];
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); });
+
+    subscribe('/config/bot', (e) => events.push(e));
+
+    await reactive.set(createNode('/other/thing', 'dir'));
+    assert.equal(events.length, 0);
+  });
+
+  it('service hot-reload: watches own config, reacts to admin update', async () => {
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb, opts) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); }, opts);
+
+    // Seed bot config
+    await reactive.set(createNode('/config/bot', 'bot-config', { token: 'old-token', lang: 'en' }));
+
+    // Service starts and subscribes to its own config
+    let reloadCount = 0;
+    let lastEvent: StoreEvent | null = null;
+    const unsub = subscribe('/config/bot', (e) => {
+      reloadCount++;
+      lastEvent = e;
+    });
+
+    // Admin updates bot token
+    const node = (await reactive.get('/config/bot'))!;
+    await reactive.set({ ...node, token: 'new-token' });
+    assert.equal(reloadCount, 1);
+    assert.equal(lastEvent!.type, 'patch');
+
+    // Admin updates another field
+    const node2 = (await reactive.get('/config/bot'))!;
+    await reactive.set({ ...node2, lang: 'ru' });
+    assert.equal(reloadCount, 2);
+
+    // Service stops — unsubscribe
+    unsub();
+    const node3 = (await reactive.get('/config/bot'))!;
+    await reactive.set({ ...node3, token: 'post-stop' });
+    assert.equal(reloadCount, 2, 'no events after unsub');
+  });
+
+  it('service watches session dir for new users', async () => {
+    const reactive = withSubscriptions(createMemoryTree());
+    const subscribe: ServiceCtx['subscribe'] = (path, cb, opts) =>
+      reactive.subscribe(path, (e) => { if ('path' in e) cb(e as StoreEvent); }, opts);
+
+    await reactive.set(createNode('/sessions', 'dir'));
+
+    // Service watches /sessions children for new logins
+    const newSessions: string[] = [];
+    const unsub = subscribe('/sessions', (e) => {
+      if (e.type === 'set') newSessions.push(e.path);
+    }, { children: true });
+
+    // Users log in
+    await reactive.set(createNode('/sessions/alice', 'session', { ts: 1 }));
+    await reactive.set(createNode('/sessions/bob', 'session', { ts: 2 }));
+    assert.deepEqual(newSessions, ['/sessions/alice', '/sessions/bob']);
+
+    // Exact update to existing session — also caught by children watch
+    const alice = (await reactive.get('/sessions/alice'))!;
+    await reactive.set({ ...alice, lastSeen: 99 });
+    assert.equal(newSessions.length, 2, 'patch events have type patch, not set');
+
+    unsub();
+  });
+});

package/src/contexts/service/index.ts

@@ -0,0 +1,43 @@
+// Treenity Service Context — Layer 2
+// Service = register(type, "service", handler) → returns { stop() }
+
+import { type NodeData, resolve as resolveCtx } from '#core';
+import { type Tree } from '#tree';
+
+// ── Types ──
+
+export type ServiceHandle = { stop(): Promise<void> };
+export type StoreEvent =
+  | { type: 'set'; path: string }
+  | { type: 'patch'; path: string }
+  | { type: 'remove'; path: string };
+export type StoreListener = (event: StoreEvent) => void;
+export type SubscribeOpts = { children?: boolean };
+export type ServiceCtx = {
+  store: Tree;
+  subscribe: (path: string, cb: StoreListener, opts?: SubscribeOpts) => () => void;
+};
+export type ServiceHandler = (node: NodeData, ctx: ServiceCtx) => Promise<ServiceHandle>;
+
+declare module '#core/context' {
+  interface ContextHandlers {
+    service: ServiceHandler;
+  }
+}
+
+// ── Bootstrap ──
+
+export async function startServices(
+  store: Tree,
+  subscribe: ServiceCtx['subscribe'],
+  path = '/sys/autostart',
+): Promise<ServiceHandle | null> {
+  const node = await store.get(path);
+  if (!node) return null;
+  const handler = resolveCtx(node.$type, 'service');
+  if (!handler) {
+    console.error(`[service] no handler for ${node.$type}`);
+    return null;
+  }
+  return await handler(node, { store, subscribe });
+}

package/src/contexts/service.ts

@@ -0,0 +1 @@
+export * from './service/index';

package/src/contexts/telegram/index.ts

@@ -0,0 +1,115 @@
+// Treenity Telegram Binding — Layer 2
+// Connects Grammy bot to Treenity tree.
+// Supports middleware pipelines, event routing, callback params.
+
+import { type ComponentData, isComponent, type NodeData, resolve } from '#core';
+import { basename } from '#core/path';
+import { type Tree } from '#tree';
+import { Bot, type Context } from 'grammy';
+
+// ── Types ──
+
+export type TgCtx = {
+  ctx: Context;
+  store: Tree;
+  node: NodeData;
+  params: string;
+  [key: string]: unknown;
+};
+
+export type TgHandler = (node: NodeData, tgCtx: TgCtx) => Promise<void>;
+export type TgMiddleware = (tgCtx: TgCtx, next: () => Promise<void>) => Promise<void>;
+
+declare module '#core/context' {
+  interface ContextHandlers {
+    telegram: TgHandler;
+  }
+}
+
+type OnComponent = ComponentData & { filter: string };
+
+// ── Middleware runner ──
+
+function runHandler(middlewares: TgMiddleware[], tgCtx: TgCtx, handler: TgHandler): Promise<void> {
+  let i = 0;
+  const next = (): Promise<void> => {
+    if (i < middlewares.length) return middlewares[i++](tgCtx, next);
+    return handler(tgCtx.node, tgCtx);
+  };
+  return next();
+}
+
+// ── Start bot from tree ──
+
+export async function startBot(store: Tree, botPath: string, middlewares: TgMiddleware[] = []) {
+  const botNode = await store.get(botPath);
+  if (!botNode) throw new Error(`Bot node not found: ${botPath}`);
+
+  const cfgVal = botNode['config'];
+  if (!isComponent(cfgVal)) throw new Error(`Bot node missing config component`);
+  const config = cfgVal as ComponentData & { token: string };
+
+  const bot = new Bot(config.token);
+  const commandsPath = botPath + '/commands';
+  const onPath = botPath + '/on';
+
+  // event handlers from /bot/on/ children
+  const { items: eventNodes } = await store.getChildren(onPath);
+  for (const eventNode of eventNodes) {
+    const onVal = eventNode['on'];
+    if (!isComponent(onVal)) throw new Error(`Event node ${eventNode.$path} missing "on" component`);
+    const on = onVal as OnComponent;
+    bot.on(on.filter as Parameters<typeof bot.on>[0], async (ctx) => {
+      const handler = resolve(eventNode.$type, 'telegram');
+      if (!handler) throw new Error(`No handler for event type "${eventNode.$type}"`);
+      const tgCtx: TgCtx = { ctx, store, node: eventNode, params: '' };
+      await runHandler(middlewares, tgCtx, handler);
+    });
+  }
+
+  // commands from /bot/commands/ children
+  const { items: commandNodes } = await store.getChildren(commandsPath);
+  for (const cmdNode of commandNodes) {
+    const cmd = basename(cmdNode.$path);
+    bot.command(cmd, async (ctx) => {
+      const handler = resolve(cmdNode.$type, 'telegram');
+      if (!handler) throw new Error(`No handler for command "${cmd}"`);
+      const tgCtx: TgCtx = { ctx, store, node: cmdNode, params: '' };
+      await runHandler(middlewares, tgCtx, handler);
+    });
+  }
+
+  // callback queries: "action" or "action:param1:param2"
+  bot.on('callback_query:data', async (ctx) => {
+    const raw = ctx.callbackQuery.data;
+    const sep = raw.indexOf(':');
+    const action = sep === -1 ? raw : raw.slice(0, sep);
+    const params = sep === -1 ? '' : raw.slice(sep + 1);
+
+    const targetNode = await store.get(`${commandsPath}/${action}`);
+    if (!targetNode) return ctx.answerCallbackQuery('Unknown action');
+    const handler = resolve(targetNode.$type, 'telegram');
+    if (!handler) return ctx.answerCallbackQuery('No handler');
+    const tgCtx: TgCtx = { ctx, store, node: targetNode, params };
+    await runHandler(middlewares, tgCtx, handler);
+    await ctx.answerCallbackQuery();
+  });
+
+  bot.catch((err) => console.error('[bot]', err.message ?? err));
+
+  // text fallback
+  bot.on('message:text', async (ctx) => {
+    const startNode = await store.get(`${commandsPath}/start`);
+    if (startNode) {
+      const handler = resolve(startNode.$type, 'telegram');
+      if (handler) {
+        const tgCtx: TgCtx = { ctx, store, node: startNode, params: '' };
+        await runHandler(middlewares, tgCtx, handler);
+      }
+    } else {
+      await ctx.reply('Try /start');
+    }
+  });
+
+  return bot;
+}

package/src/contexts/text/index.test.ts

@@ -0,0 +1,31 @@
+import { resolve } from '#core';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import './index';
+
+// Text binding registers on import, but clearRegistry would wipe them.
+// So we test after import, without clearing.
+
+describe('Text binding', () => {
+  it('string renders value', () => {
+    const h = resolve('string', 'text');
+    assert.ok(h);
+    assert.equal(h({ value: 'hello' }), 'hello');
+    assert.equal(h({ value: 42 }), '42');
+    assert.equal(h({}), '');
+  });
+
+  it('number renders value', () => {
+    const h = resolve('number', 'text');
+    assert.ok(h);
+    assert.equal(h({ value: 3.14 }), '3.14');
+    assert.equal(h({}), '0');
+  });
+
+  it('boolean renders yes/no', () => {
+    const h = resolve('boolean', 'text');
+    assert.ok(h);
+    assert.equal(h({ value: true }), 'yes');
+    assert.equal(h({ value: false }), 'no');
+  });
+});

package/src/contexts/text/index.ts

@@ -0,0 +1,18 @@
+// Text context — plain text rendering for CLI/server
+// Layer 2 binding. Registers "text" context handlers for primitive types.
+// Block-type text handlers belong in their mods
+
+import { register } from '#core';
+
+export type TextHandler = (data: Record<string, unknown>) => string;
+
+declare module '#core/context' {
+  interface ContextHandlers {
+    text: TextHandler;
+  }
+}
+
+// Primitives
+register('string', 'text', (data) => String(data.value ?? ''));
+register('number', 'text', (data) => String(data.value ?? 0));
+register('boolean', 'text', (data) => data.value ? 'yes' : 'no');

package/src/contexts/text.ts

@@ -0,0 +1 @@
+export * from './text/index';

package/src/core/component.ts

@@ -0,0 +1,151 @@
+// ── ACL ──
+
+export type GroupPerm = { g: string; p: number };
+export const R = 1,
+  W = 2,
+  A = 4,
+  S = 8;
+
+// TODO: K extends `$${infer N}` ? never : K
+// TODO: fix ComponentData and NodeData types. it should be generic types of its contents
+export type ComponentData<T = Record<string, unknown>> = T & {
+  $type: string;
+  $acl?: GroupPerm[];
+};
+
+export type NodeData<T = Record<string, unknown>> = ComponentData<T> & {
+  $path: string;
+  $owner?: string;
+  $rev?: number;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export type Class<T = unknown> = new (...args: any[]) => T;
+
+// Accept string, object with $type, or registered class (registerType stamps $type on constructor)
+export type TypeId<T = unknown> = string | { $type: string } | Class<T>;
+
+// ── Type normalization ──
+// Dot-less types belong to treenity namespace: 'dir' → 't.dir', 'ref' → 't.ref'
+// Types with dots are already namespaced and returned as-is
+export function normalizeType(type: TypeId): string {
+  if (typeof type === 'string') return type.includes('.') ? type : `t.${type}`;
+  if ('$type' in type && typeof (type as any).$type === 'string') return normalizeType((type as any).$type);
+  throw new Error('TypeId: object has no $type property');
+}
+
+// ── Utils ──
+
+export function isComponent(value: unknown): value is ComponentData {
+  return typeof value === 'object' && value !== null && '$type' in value;
+}
+
+export function getCompByKey(node: NodeData, key: string): ComponentData | undefined {
+  const v = key === '' ? node : node[key];
+  return isComponent(v) ? v : undefined;
+}
+
+export const AnyType = { $type: 'any' };
+
+export function isOfType<T>(value: unknown, type: TypeId): value is ComponentData<T> {
+  if (!isComponent(value)) return false;
+  const t = normalizeType(type);
+  return t === 't.any' || normalizeType(value.$type) === t;
+}
+
+// ── Ref ──
+export type Ref = { $type?: string; $ref: string; $map?: string };
+
+export function ref(path: string): Ref {
+  return { $type: 'ref', $ref: path };
+}
+
+export function isRef(value: unknown): value is Ref {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.$ref === 'string' && (!v.$type || v.$type === 'ref' || v.$type === 't.ref');
+}
+
+// ── Node ──
+
+export function assertNonSystemName(name: string) {
+  if (name.startsWith('$')) throw new Error(`Component name cannot start with $: ${name}`);
+}
+
+export function createNode<T = any, C = Record<string, ComponentData<any>>>(
+  path: string,
+  type: TypeId,
+  data?: T,
+  components?: C): NodeData<T & C> {
+
+  const node: NodeData<T & C> = { $path: path, $type: normalizeType(type) } as NodeData<T & C>;
+  if (components) Object.keys(components).forEach(assertNonSystemName);
+  if (data) Object.keys(data).forEach(assertNonSystemName);
+
+  Object.assign(node, components, data);
+
+  return node;
+}
+
+export function getComponentField<T = unknown>(
+  node: NodeData,
+  type: TypeId<T>,
+  field?: string,
+): [ComponentData<T>, string] | undefined {
+  if (field != null) {
+    const v = field === '' ? node : node[field];
+    if (isOfType<T>(v, type)) return [v, field];
+    return;
+  }
+  if (isOfType<T>(node, type)) return [node, ''];
+  for (const [k, v] of Object.entries(node)) {
+    if (k.startsWith('$')) continue;
+    if (isOfType<T>(v, type)) return [v, k];
+  }
+}
+
+export function getComponent<T = unknown>(
+  node: NodeData,
+  type: TypeId<T>,
+  field?: string,
+): ComponentData<T> | undefined {
+  return getComponentField(node, type, field)?.[0];
+}
+
+export function getComponents<T = unknown>(
+  node: NodeData,
+  type: TypeId<T>,
+): [string, ComponentData<T>][] {
+  const result: [string, ComponentData<T>][] = [];
+  if (isOfType<T>(node, type)) result.push(['', node]);
+  for (const [k, v] of Object.entries(node)) {
+    if (k.startsWith('$')) continue;
+    if (isOfType<T>(v, type)) result.push([k, v]);
+  }
+  return result;
+}
+
+// ── $ ↔ _ key mapping (Mongo/sift compat) ──
+
+export function toStorageKeys(node: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(node))
+    out[k.startsWith('$') ? `_${k.slice(1)}` : k] = v;
+  return out;
+}
+
+export function fromStorageKeys(doc: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(doc)) {
+    if (k === '_id') continue;
+    out[k.startsWith('_') ? `$${k.slice(1)}` : k] = v;
+  }
+  return out;
+}
+
+export function removeComponent(node: NodeData, name: string): boolean {
+  assertNonSystemName(name);
+  if (!isComponent(node[name])) return false;
+  delete node[name];
+  return true;
+}