@jumentix/cli-init 0.0.0

package/templates/frontend/src/data/db.ts

@@ -0,0 +1,114 @@
+import {
+  createClient, deleteDatabase, isCanaError, type CanaClient
+} from '@jumentix/cana';
+
+import {
+  DATABASE_NAME, META_STORE, SCHEMA_META_ID, buildCanaSchema, buildCanaStores, schemaFingerprint
+} from '@/data/canaSchema';
+
+export type CanaBootStatus = 'ok' | 'unavailable';
+
+let client: CanaClient | null = null;
+let bootStatus: CanaBootStatus | null = null;
+let currentName = DATABASE_NAME;
+
+export const isCanaOpen = (): boolean => client !== null;
+
+export const canaBootStatus = (): CanaBootStatus | null => bootStatus;
+
+export const getCanaClient = (): CanaClient => {
+  if (!client) {
+    throw new Error('Cana is not open.');
+  }
+  return client;
+};
+
+const openFresh = async (name: string): Promise<CanaClient> => {
+  const schema = buildCanaSchema();
+  const next = createClient({ name, schema, fallback: false });
+  await next.open();
+  const fingerprint = schemaFingerprint(schema.stores);
+  const meta = next.table(META_STORE);
+  const recorded = await meta.get(SCHEMA_META_ID) as { fingerprint?: string } | undefined;
+  if (recorded && recorded.fingerprint !== fingerprint) {
+    await next.close();
+    await deleteDatabase(name);
+    const reopened = createClient({ name, schema, fallback: false });
+    await reopened.open();
+    await reopened.table(META_STORE).put({
+      id: SCHEMA_META_ID, fingerprint, version: schema.version
+    });
+    return reopened;
+  }
+  if (!recorded) {
+    await meta.put({ id: SCHEMA_META_ID, fingerprint, version: schema.version });
+  }
+  return next;
+};
+
+export const openCana = async (name: string = DATABASE_NAME): Promise<CanaClient> => {
+  if (client && currentName === name) return client;
+  if (client) {
+    await client.close();
+    client = null;
+  }
+  currentName = name;
+  try {
+    client = await openFresh(name);
+    bootStatus = 'ok';
+    return client;
+  } catch (error) {
+    if (isCanaError(error) && (error.code === 'UpgradeFailed' || error.code === 'UpgradeBlocked')) {
+      await deleteDatabase(name);
+      client = await openFresh(name);
+      bootStatus = 'ok';
+      return client;
+    }
+    if (isCanaError(error) && error.code === 'Unavailable') {
+      bootStatus = 'unavailable';
+      client = null;
+      throw error;
+    }
+    bootStatus = 'unavailable';
+    client = null;
+    throw error;
+  }
+};
+
+export const closeCana = async (): Promise<void> => {
+  if (!client) return;
+  await client.close();
+  client = null;
+};
+
+export const wipeCanaDatabase = async (): Promise<void> => {
+  const name = currentName;
+  await closeCana();
+  await deleteDatabase(name);
+  await openCana(name);
+};
+
+/**
+ * Boot path: open IndexedDB before the SPA mounts. Returns `unavailable` when
+ * the origin has no IndexedDB (no localStorage fallback — the seed is
+ * offline-first, not degraded-memory).
+ */
+export const bootCana = async (): Promise<CanaBootStatus> => {
+  try {
+    await openCana(DATABASE_NAME);
+    return 'ok';
+  } catch {
+    bootStatus = 'unavailable';
+    return 'unavailable';
+  }
+};
+
+export const exposeCanaTestHooks = (): void => {
+  if (typeof window === 'undefined') return;
+  const hook = window as Window & {
+    __jumentixWipeCana?: () => Promise<void>;
+    __jumentixObjectStores?: () => string[];
+  };
+  hook.__jumentixWipeCana = wipeCanaDatabase;
+  hook.__jumentixObjectStores = () => buildCanaStores().map((store) => store.name);
+};

package/templates/frontend/src/data/localRepository.ts

@@ -0,0 +1,125 @@
+import { parseListSort, runListQuery, type TListFilters } from '@jumentix/persistence-contracts';
+
+import type { ListPage, ListQuery } from '@/contracts/listSchema';
+import { fieldDescriptors } from '@/contracts/formSchema';
+import {
+  entityTable, entityTableByStore, type EntityTableSpec
+} from '@/data/canaSchema';
+import { getCanaClient, isCanaOpen } from '@/data/db';
+
+const asRecords = <T extends Record<string, unknown>>(
+  rows: readonly unknown[]
+): T[] => rows as T[];
+
+const indexedQuery = async <T extends Record<string, unknown>>(
+  table: EntityTableSpec,
+  query: ListQuery
+): Promise<{ records: T[]; usedIndex?: string }> => {
+  const store = getCanaClient().table(table.storeName);
+  const sort = parseListSort(query.sort);
+  const primary = sort?.[0];
+  const canIndex = Boolean(
+    primary && table.indexes.includes(primary.field) && !query.q && !query.filter
+  );
+  if (canIndex && primary) {
+    const records = asRecords<T>(await store.query({
+      index: primary.field,
+      direction: primary.direction === 'desc' ? 'prev' : 'next'
+    }));
+    return { records, usedIndex: primary.field };
+  }
+  return { records: asRecords<T>(await store.query()) };
+};
+
+export const listLocal = async <T extends Record<string, unknown> = Record<string, unknown>>(
+  schemaName: string,
+  query: ListQuery & { searchFields?: string[] } = {}
+): Promise<ListPage<T> & { usedIndex?: string }> => {
+  const table = entityTable(schemaName);
+  const { records, usedIndex } = await indexedQuery<T>(table, query);
+  const page = query.page ?? 1;
+  const size = query.size ?? 30;
+  const result = runListQuery(records, query.filter as TListFilters | undefined, {
+    page,
+    size,
+    sort: parseListSort(query.sort),
+    q: query.q,
+    searchFields: query.searchFields,
+    includeDeleted: false
+  });
+  return {
+    result: result.result ?? [],
+    page: result.page ?? page,
+    size: result.size ?? size,
+    total: result.total,
+    usedIndex
+  };
+};
+
+export const getLocal = async <T extends Record<string, unknown> = Record<string, unknown>>(
+  schemaName: string,
+  key: string
+): Promise<T | undefined> => {
+  const table = entityTable(schemaName);
+  const record = await getCanaClient().table(table.storeName).get(key);
+  return record as T | undefined;
+};
+
+export const countLocal = async (schemaName: string): Promise<number> => {
+  const page = await listLocal(schemaName, { page: 1, size: 1 });
+  return page.total;
+};
+
+export const resolveRelations = async (
+  schemaName: string,
+  row: Record<string, unknown>
+): Promise<Record<string, unknown>> => {
+  const joined: Record<string, unknown> = { ...row };
+  await Promise.all(fieldDescriptors(schemaName).map(async (descriptor) => {
+    const { relation } = descriptor;
+    if (!relation) return;
+    const target = entityTable(relation.entity);
+    const store = getCanaClient().table(target.storeName);
+    if (relation.kind === 'belongsTo') {
+      const key = row[relation.field];
+      if (key == null || key === '') return;
+      const related = await store.get(String(key));
+      if (related) {
+        joined[`${descriptor.name}Record`] = related;
+        joined[`${descriptor.name}Label`] = (related as Record<string, unknown>)[relation.display]
+          ?? key;
+      }
+      return;
+    }
+    const match = String(row[target.keyPath] ?? row.id ?? '');
+    if (!match) return;
+    try {
+      const children = await store.query({ index: relation.field, equals: match });
+      joined[descriptor.name] = children;
+    } catch {
+      joined[descriptor.name] = [];
+    }
+  }));
+  return joined;
+};
+
+export const subscribeLocal = (
+  schemaName: string,
+  listener: () => void
+): (() => void) => {
+  if (!isCanaOpen()) return () => undefined;
+  const table = entityTable(schemaName);
+  const relatedStores = new Set<string>([table.storeName]);
+  for (const descriptor of fieldDescriptors(schemaName)) {
+    if (descriptor.relation) {
+      relatedStores.add(entityTable(descriptor.relation.entity).storeName);
+    }
+  }
+  return getCanaClient().subscribe((event) => {
+    if (relatedStores.has(event.store)) listener();
+  });
+};
+
+export const storeForChange = (storeName: string): EntityTableSpec | undefined => (
+  entityTableByStore(storeName)
+);

package/templates/frontend/src/data/outbox.ts

@@ -0,0 +1,258 @@
+/* Sequential IndexedDB + REST: one outbox intent at a time. */
+/* eslint-disable no-await-in-loop, no-continue */
+import { apiErrorStatus } from '@/contracts/errors';
+import { getSharedApiClient } from '@/contracts/apiClient';
+import { useAuthStore } from '@/stores/auth';
+import { useNotificationStore } from '@/stores/notifications';
+import { OUTBOX_STORE, entityTable } from '@/data/canaSchema';
+import { getCanaClient, isCanaOpen } from '@/data/db';
+
+export type OutboxKind = 'create' | 'update' | 'delete';
+export type SyncFlag = 'pending' | 'synced';
+
+export interface OutboxIntent {
+  opId: string;
+  entity: string;
+  kind: OutboxKind;
+  key: string;
+  payload: Record<string, unknown>;
+  beforeImage?: Record<string, unknown>;
+  createdAt: string;
+  attempts: number;
+  dependsOn?: string;
+  operations: { create: string; update: string; delete: string };
+}
+
+const SYNC_FIELD = '_sync';
+
+const stripLocal = (record: Record<string, unknown>): Record<string, unknown> => {
+  const next = { ...record };
+  delete next[SYNC_FIELD];
+  for (const key of Object.keys(next)) {
+    if (key.endsWith('Record') || key.endsWith('Label')) delete next[key];
+  }
+  return next;
+};
+
+const newOpId = (): string => {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    crypto.getRandomValues(bytes);
+  }
+  return `op-${Date.now()}-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+};
+
+export const listOutbox = async (): Promise<OutboxIntent[]> => {
+  if (!isCanaOpen()) return [];
+  const rows = await getCanaClient().table(OUTBOX_STORE).query({
+    index: 'createdAt',
+    direction: 'next'
+  });
+  return [...rows] as OutboxIntent[];
+};
+
+const pendingForKey = async (entity: string, key: string): Promise<OutboxIntent | undefined> => {
+  const all = await listOutbox();
+  return all.find((intent) => intent.entity === entity && intent.key === key);
+};
+
+export const enqueueMutation = async (input: {
+  entity: string;
+  kind: OutboxKind;
+  key?: string;
+  payload: Record<string, unknown>;
+  operations: OutboxIntent['operations'];
+}): Promise<Record<string, unknown>> => {
+  const table = entityTable(input.entity);
+  const { keyPath } = table;
+  const payload = stripLocal(
+    JSON.parse(JSON.stringify(input.payload)) as Record<string, unknown>
+  );
+  const key = input.key
+    ?? String(payload[keyPath] ?? (payload.id = (
+      typeof crypto !== 'undefined' && crypto.randomUUID
+        ? crypto.randomUUID()
+        : `id-${Date.now()}`
+    )));
+  payload[keyPath] = key;
+  const client = getCanaClient();
+  const existing = await pendingForKey(input.entity, key);
+  const beforeImage = input.kind === 'create'
+    ? undefined
+    : (await client.table(table.storeName).get(key) as Record<string, unknown> | undefined);
+
+  const intent: OutboxIntent = existing && existing.kind !== 'delete'
+    ? {
+      ...existing,
+      kind: existing.kind === 'create' ? 'create' : input.kind,
+      payload: existing.kind === 'create' ? { ...existing.payload, ...payload } : payload,
+      createdAt: existing.createdAt
+    }
+    : {
+      opId: newOpId(),
+      entity: input.entity,
+      kind: input.kind,
+      key,
+      payload,
+      beforeImage: beforeImage ? stripLocal(beforeImage) : undefined,
+      createdAt: new Date().toISOString(),
+      attempts: 0,
+      dependsOn: existing?.kind === 'create' ? existing.opId : undefined,
+      operations: input.operations
+    };
+
+  const localRecord = input.kind === 'delete'
+    ? {
+      ...JSON.parse(JSON.stringify(beforeImage ?? {})),
+      [keyPath]: key,
+      deletedAt: new Date().toISOString(),
+      [SYNC_FIELD]: 'pending' as SyncFlag
+    }
+    : { ...payload, [SYNC_FIELD]: 'pending' as SyncFlag };
+
+  const result = await client.transaction('readwrite', [table.storeName, OUTBOX_STORE], async (scope) => {
+    await scope.table(table.storeName).put(localRecord);
+    await scope.table(OUTBOX_STORE).put(intent);
+    return localRecord;
+  });
+  if (result.outcome !== 'committed' || !result.result) {
+    throw new Error('Local write did not commit.');
+  }
+  return result.result as Record<string, unknown>;
+};
+
+const isOnline = (): boolean => (
+  typeof navigator === 'undefined' || navigator.onLine !== false
+);
+
+const headers = (): { Authorization: string } => {
+  const auth = useAuthStore();
+  if (!auth.token) throw new Error('No authenticated session.');
+  return { Authorization: auth.token };
+};
+
+const compensate = async (intent: OutboxIntent, dependents: OutboxIntent[]): Promise<void> => {
+  const client = getCanaClient();
+  const chain = [intent, ...dependents.filter((item) => item.dependsOn === intent.opId)];
+  await client.transaction(
+    'readwrite',
+    [...new Set([...chain.map((item) => entityTable(item.entity).storeName), OUTBOX_STORE])],
+    async (scope) => {
+      for (const item of chain) {
+        const store = scope.table(entityTable(item.entity).storeName);
+        if (item.kind === 'create') {
+          await store.delete(item.key);
+        } else if (item.beforeImage) {
+          await store.put({ ...item.beforeImage, [SYNC_FIELD]: 'synced' });
+        }
+        await scope.table(OUTBOX_STORE).delete(item.opId);
+      }
+    }
+  );
+};
+
+let draining = false;
+let drainAgain = false;
+
+const replayIntent = async (intent: OutboxIntent): Promise<Record<string, unknown> | undefined> => {
+  const api = getSharedApiClient();
+  const auth = headers();
+  if (intent.kind === 'create') {
+    return api.request<Record<string, unknown>>({
+      operationId: intent.operations.create,
+      body: stripLocal(intent.payload),
+      headers: auth
+    });
+  }
+  if (intent.kind === 'update') {
+    return api.request<Record<string, unknown>>({
+      operationId: intent.operations.update,
+      pathParams: { id: intent.key },
+      body: { ...stripLocal(intent.payload), id: intent.key },
+      headers: auth
+    });
+  }
+  await api.request({
+    operationId: intent.operations.delete,
+    pathParams: { id: intent.key },
+    headers: auth
+  });
+  return undefined;
+};
+
+const confirmIntent = async (
+  intent: OutboxIntent,
+  response: Record<string, unknown> | undefined
+): Promise<void> => {
+  const table = entityTable(intent.entity);
+  await getCanaClient().transaction(
+    'readwrite',
+    [table.storeName, OUTBOX_STORE],
+    async (scope) => {
+      if (intent.kind === 'delete') {
+        await scope.table(table.storeName).delete(intent.key);
+      } else {
+        const confirmed = stripLocal(response ?? intent.payload);
+        await scope.table(table.storeName).put({ ...confirmed, [SYNC_FIELD]: 'synced' });
+      }
+      await scope.table(OUTBOX_STORE).delete(intent.opId);
+    }
+  );
+};
+
+const rejectClientError = async (intent: OutboxIntent, error: unknown): Promise<void> => {
+  const rest = await listOutbox();
+  await compensate(intent, rest);
+  useNotificationStore().reject({
+    entity: intent.entity,
+    key: intent.key,
+    kind: intent.kind,
+    message: error instanceof Error ? error.message : String(error),
+    reopen: intent.kind === 'delete' ? undefined : intent.payload
+  });
+};
+
+const drainOne = async (intent: OutboxIntent, pendingIds: Set<string>): Promise<'stop' | 'next'> => {
+  if (intent.dependsOn && pendingIds.has(intent.dependsOn)) return 'next';
+  try {
+    const response = await replayIntent(intent);
+    await confirmIntent(intent, response);
+    pendingIds.delete(intent.opId);
+  } catch (error) {
+    const status = apiErrorStatus(error);
+    if (status === 401) return 'stop';
+    if (status !== undefined && status >= 400 && status < 500) {
+      await rejectClientError(intent, error);
+      pendingIds.delete(intent.opId);
+      return 'next';
+    }
+    const retried = { ...intent, attempts: intent.attempts + 1 };
+    await getCanaClient().table(OUTBOX_STORE).put(retried);
+  }
+  return 'next';
+};
+
+export const drainOutbox = async (): Promise<void> => {
+  if (!isCanaOpen() || !isOnline()) return;
+  if (draining) {
+    drainAgain = true;
+    return;
+  }
+  draining = true;
+  try {
+    do {
+      drainAgain = false;
+      const intents = await listOutbox();
+      const pendingIds = new Set(intents.map((item) => item.opId));
+      for (const intent of intents) {
+        const step = await drainOne(intent, pendingIds);
+        if (step === 'stop') return;
+      }
+    } while (drainAgain);
+  } finally {
+    draining = false;
+  }
+};

package/templates/frontend/src/data/pwa.ts

@@ -0,0 +1,26 @@
+import { useNotificationStore } from '@/stores/notifications';
+import { t } from '@/i18n';
+
+const pwaEnabled = (): boolean => {
+  if (typeof window === 'undefined' || !('serviceWorker' in navigator)) return false;
+  return Boolean(import.meta.env.PROD) || import.meta.env.VITE_PWA === '1';
+};
+
+export const registerSW = (): void => {
+  if (!pwaEnabled()) return;
+  navigator.serviceWorker.register('./sw.js').then((registration) => {
+    registration.addEventListener('updatefound', () => {
+      const worker = registration.installing;
+      if (!worker) return;
+      worker.addEventListener('statechange', () => {
+        if (worker.state === 'installed' && navigator.serviceWorker.controller) {
+          useNotificationStore().push({
+            kind: 'update',
+            title: t('pwa.updateTitle'),
+            message: t('pwa.updateBody')
+          });
+        }
+      });
+    });
+  }).catch(() => undefined);
+};