@svadmin/core 0.0.3 → 0.3.0

package/src/inferencer.ts

@@ -0,0 +1,247 @@
+/**
+ * @svadmin/inferencer
+ *
+ * Analyzes API response data and infers ResourceDefinition + FieldDefinition[].
+ * Can also generate copy-paste-ready Svelte component code.
+ */
+import type { FieldDefinition, ResourceDefinition } from '@svadmin/core';
+
+// ─── Field Type Inference ────────────────────────────────────
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\//;
+const IMAGE_RE = /\.(png|jpe?g|gif|svg|webp|avif|ico)(\?.*)?$/i;
+const PHONE_RE = /^\+?[\d\s\-()]{7,}$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})/;
+const COLOR_RE = /^#([0-9a-fA-F]{3,8})$/;
+
+type InferredType = FieldDefinition['type'];
+
+/**
+ * Infer the svadmin field type from a single sample value.
+ */
+export function inferFieldType(key: string, value: unknown): InferredType {
+  if (value === null || value === undefined) return 'text';
+
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return 'number';
+
+  if (Array.isArray(value)) {
+    if (value.length > 0 && typeof value[0] === 'string') {
+      if (value.every(v => typeof v === 'string' && IMAGE_RE.test(v))) return 'images';
+      return 'tags';
+    }
+    return 'tags';
+  }
+
+  if (typeof value === 'object') return 'json';
+
+  if (typeof value === 'string') {
+    if (COLOR_RE.test(value)) return 'color';
+    if (EMAIL_RE.test(value)) return 'email';
+    if (IMAGE_RE.test(value)) return 'image';
+    if (URL_RE.test(value)) return 'url';
+    if (PHONE_RE.test(value)) return 'phone';
+    if (ISO_DATE_RE.test(value)) return 'date';
+    if (value.length > 200) return 'textarea';
+
+    // Heuristic: key name hints
+    const lk = key.toLowerCase();
+    if (lk.includes('email')) return 'email';
+    if (lk.includes('phone') || lk.includes('tel') || lk.includes('mobile')) return 'phone';
+    if (lk.includes('url') || lk.includes('link') || lk.includes('website')) return 'url';
+    if (lk.includes('avatar') || lk.includes('image') || lk.includes('photo') || lk.includes('thumbnail') || lk.includes('logo')) return 'image';
+    if (lk.includes('color') || lk.includes('colour')) return 'color';
+    if (lk.includes('description') || lk.includes('content') || lk.includes('body') || lk.includes('bio') || lk.includes('summary')) return 'textarea';
+    if (lk === 'created_at' || lk === 'updated_at' || lk.endsWith('_at') || lk.endsWith('_date') || lk.includes('date')) return 'date';
+
+    return 'text';
+  }
+
+  return 'text';
+}
+
+// ─── Relation Detection ──────────────────────────────────────
+
+const RELATION_SUFFIXES = ['_id', 'Id', '_ID'];
+
+function isLikelyRelation(key: string): string | null {
+  for (const suffix of RELATION_SUFFIXES) {
+    if (key.endsWith(suffix)) {
+      const resource = key.slice(0, -suffix.length);
+      // Pluralize naively
+      return resource.endsWith('s') ? resource : resource + 's';
+    }
+  }
+  return null;
+}
+
+// ─── Core: Infer from Sample Data ────────────────────────────
+
+export interface InferResult {
+  fields: FieldDefinition[];
+  resource: ResourceDefinition;
+  code: string;
+}
+
+/**
+ * Analyze a sample data array and produce a ResourceDefinition.
+ * @param resourceName - Name of the resource (e.g. "posts")
+ * @param sampleData  - An array of records from the API
+ * @param options      - Additional configuration
+ */
+export function inferResource(
+  resourceName: string,
+  sampleData: Record<string, unknown>[],
+  options: {
+    primaryKey?: string;
+    label?: string;
+  } = {}
+): InferResult {
+  const primaryKey = options.primaryKey ?? 'id';
+  const label = options.label ?? capitalize(resourceName);
+
+  if (!sampleData.length) {
+    return {
+      fields: [],
+      resource: { name: resourceName, label, fields: [], primaryKey },
+      code: `// No data available to infer fields for "${resourceName}".`,
+    };
+  }
+
+  // Gather all unique keys across all records
+  const keySet = new Set<string>();
+  for (const row of sampleData) {
+    for (const k of Object.keys(row)) keySet.add(k);
+  }
+
+  // For each key, infer from all non-null values
+  const fields: FieldDefinition[] = [];
+  for (const key of keySet) {
+    // Collect non-null values
+    const values = sampleData
+      .map(r => r[key])
+      .filter(v => v !== null && v !== undefined);
+
+    const sampleValue = values[0];
+    let inferredType = inferFieldType(key, sampleValue);
+
+    // Cross-validate: if most values for this key are of a different type, use majority
+    const typeCounts = new Map<InferredType, number>();
+    for (const v of values) {
+      const t = inferFieldType(key, v);
+      typeCounts.set(t, (typeCounts.get(t) ?? 0) + 1);
+    }
+    let maxCount = 0;
+    for (const [t, count] of typeCounts) {
+      if (count > maxCount) {
+        maxCount = count;
+        inferredType = t;
+      }
+    }
+
+    // Check for relation
+    const relatedResource = isLikelyRelation(key);
+
+    // Check if it looks like a select (few unique string values)
+    const uniqueStrings = new Set(values.filter(v => typeof v === 'string') as string[]);
+    const isSelect = inferredType === 'text' && uniqueStrings.size > 1 && uniqueStrings.size <= 10 && values.length >= 5;
+
+    const field: FieldDefinition = {
+      key,
+      label: humanize(key),
+      type: relatedResource ? 'relation' : isSelect ? 'select' : inferredType,
+      sortable: inferredType === 'text' || inferredType === 'number' || inferredType === 'date',
+      searchable: inferredType === 'text' || inferredType === 'email',
+      showInList: key !== primaryKey && inferredType !== 'textarea' && inferredType !== 'json' && inferredType !== 'richtext',
+      showInForm: key !== primaryKey,
+    };
+
+    if (relatedResource) {
+      field.resource = relatedResource;
+      field.optionLabel = 'name';
+      field.optionValue = 'id';
+    }
+
+    if (isSelect) {
+      field.options = [...uniqueStrings].map(v => ({ label: capitalize(v), value: v }));
+    }
+
+    fields.push(field);
+  }
+
+  // Sort: primaryKey first, then alphabetically
+  fields.sort((a, b) => {
+    if (a.key === primaryKey) return -1;
+    if (b.key === primaryKey) return 1;
+    return a.key.localeCompare(b.key);
+  });
+
+  const resource: ResourceDefinition = {
+    name: resourceName,
+    label,
+    primaryKey,
+    fields,
+    canCreate: true,
+    canEdit: true,
+    canDelete: true,
+    canShow: true,
+  };
+
+  const code = generateCode(resource);
+
+  return { fields, resource, code };
+}
+
+// ─── Code Generation ─────────────────────────────────────────
+
+function generateCode(resource: ResourceDefinition): string {
+  const fieldsCode = resource.fields.map(f => {
+    const lines = [
+      `    { key: '${f.key}', label: '${f.label}', type: '${f.type}'`,
+    ];
+    if (f.sortable) lines.push(`      sortable: true`);
+    if (f.searchable) lines.push(`      searchable: true`);
+    if (f.showInList === false) lines.push(`      showInList: false`);
+    if (f.showInForm === false) lines.push(`      showInForm: false`);
+    if (f.resource) {
+      lines.push(`      resource: '${f.resource}'`);
+      lines.push(`      optionLabel: '${f.optionLabel}'`);
+      lines.push(`      optionValue: '${f.optionValue}'`);
+    }
+    if (f.options) {
+      lines.push(`      options: ${JSON.stringify(f.options)}`);
+    }
+
+    return lines.join(',\n') + ' }';
+  }).join(',\n');
+
+  return `import type { ResourceDefinition } from '@svadmin/core';
+
+export const ${resource.name}Resource: ResourceDefinition = {
+  name: '${resource.name}',
+  label: '${resource.label}',
+  primaryKey: '${resource.primaryKey ?? 'id'}',
+  canCreate: true,
+  canEdit: true,
+  canDelete: true,
+  canShow: true,
+  fields: [
+${fieldsCode}
+  ],
+};
+`;
+}
+
+// ─── Utilities ───────────────────────────────────────────────
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function humanize(key: string): string {
+  return key
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, c => c.toUpperCase());
+}

package/src/live-sse.ts

@@ -0,0 +1,146 @@
+/**
+ * SSE (Server-Sent Events) LiveProvider
+ *
+ * Connects to an SSE endpoint and dispatches LiveEvents to subscribers.
+ * The server should emit events as JSON matching the LiveEvent shape:
+ *   data: { "type": "INSERT", "resource": "posts", "payload": {...} }
+ *
+ * Optionally, named SSE events can be used:
+ *   event: posts
+ *   data: { "type": "INSERT", "payload": {...} }
+ */
+import type { LiveProvider, LiveEvent } from './live';
+
+export interface SSELiveProviderOptions {
+  /** SSE endpoint URL, e.g. "https://api.example.com/events" */
+  url: string;
+  /** Optional EventSource init options (e.g. withCredentials) */
+  eventSourceInit?: EventSourceInit;
+  /** Optional callback when connection opens */
+  onOpen?: () => void;
+  /** Optional callback for connection errors */
+  onError?: (event: Event) => void;
+}
+
+export function createSSELiveProvider(options: SSELiveProviderOptions): LiveProvider & { disconnect: () => void; getStatus: () => 'connecting' | 'connected' | 'disconnected' } {
+  const { url, eventSourceInit } = options;
+
+  type Callback = (event: LiveEvent) => void;
+  const subscribers = new Map<string, Set<Callback>>();
+  let eventSource: EventSource | null = null;
+  let status: 'connecting' | 'connected' | 'disconnected' = 'disconnected';
+
+  function connect() {
+    if (eventSource) return;
+    if (typeof EventSource === 'undefined') return;
+
+    status = 'connecting';
+    eventSource = new EventSource(url, eventSourceInit);
+
+    eventSource.onopen = () => {
+      status = 'connected';
+      options.onOpen?.();
+    };
+
+    // Listen for generic "message" events
+    eventSource.onmessage = (msgEvent) => {
+      dispatchEvent(msgEvent.data);
+    };
+
+    eventSource.onerror = (event) => {
+      // EventSource auto-reconnects by default
+      if (eventSource?.readyState === EventSource.CLOSED) {
+        status = 'disconnected';
+      }
+      options.onError?.(event);
+    };
+
+    // Also listen for resource-specific named events
+    for (const resource of subscribers.keys()) {
+      if (resource !== '*') {
+        addNamedListener(resource);
+      }
+    }
+  }
+
+  function addNamedListener(resource: string) {
+    if (!eventSource) return;
+    eventSource.addEventListener(resource, ((event: MessageEvent) => {
+      try {
+        const parsed = JSON.parse(event.data);
+        const liveEvent: LiveEvent = {
+          type: parsed.type,
+          resource: parsed.resource ?? resource,
+          payload: parsed.payload ?? parsed,
+        };
+        notifySubscribers(liveEvent);
+      } catch {
+        // ignore non-JSON
+      }
+    }) as EventListener);
+  }
+
+  function dispatchEvent(data: string) {
+    try {
+      const event: LiveEvent = JSON.parse(data);
+      if (event.type && event.resource) {
+        notifySubscribers(event);
+      }
+    } catch {
+      // ignore non-JSON
+    }
+  }
+
+  function notifySubscribers(event: LiveEvent) {
+    const callbacks = subscribers.get(event.resource);
+    if (callbacks) {
+      for (const cb of callbacks) cb(event);
+    }
+    // Wildcard subscribers
+    const wildcardCallbacks = subscribers.get('*');
+    if (wildcardCallbacks) {
+      for (const cb of wildcardCallbacks) cb(event);
+    }
+  }
+
+  function disconnect() {
+    if (eventSource) {
+      eventSource.close();
+      eventSource = null;
+    }
+    status = 'disconnected';
+  }
+
+  return {
+    subscribe({ resource, callback }) {
+      if (!subscribers.has(resource)) {
+        subscribers.set(resource, new Set());
+      }
+      subscribers.get(resource)!.add(callback);
+
+      // Connect if not already
+      if (!eventSource && typeof EventSource !== 'undefined') {
+        connect();
+      }
+      // Add named listener for this resource if connected
+      if (eventSource && resource !== '*') {
+        addNamedListener(resource);
+      }
+
+      return () => {
+        const callbacks = subscribers.get(resource);
+        if (callbacks) {
+          callbacks.delete(callback);
+          if (callbacks.size === 0) subscribers.delete(resource);
+        }
+        if (subscribers.size === 0) disconnect();
+      };
+    },
+
+    disconnect,
+
+    getStatus() {
+      return status;
+    },
+  };
+}

package/src/live-websocket.ts

@@ -0,0 +1,141 @@
+/**
+ * WebSocket LiveProvider
+ *
+ * Connects to a WebSocket server and dispatches LiveEvents to subscribers.
+ * The server is expected to send JSON messages matching the LiveEvent shape:
+ *   { type: 'INSERT' | 'UPDATE' | 'DELETE', resource: string, payload: {...} }
+ */
+import type { LiveProvider, LiveEvent } from './live';
+
+export interface WebSocketLiveProviderOptions {
+  /** WebSocket server URL, e.g. "wss://api.example.com/ws" */
+  url: string;
+  /** Reconnect delay in ms (default 3000) */
+  reconnectDelay?: number;
+  /** Max reconnect attempts (default Infinity) */
+  maxReconnects?: number;
+  /** Optional callback when connection opens */
+  onOpen?: () => void;
+  /** Optional callback when connection closes */
+  onClose?: (event: CloseEvent) => void;
+  /** Optional callback for connection errors */
+  onError?: (event: Event) => void;
+}
+
+export function createWebSocketLiveProvider(options: WebSocketLiveProviderOptions): LiveProvider & { disconnect: () => void; getStatus: () => 'connecting' | 'connected' | 'disconnected' } {
+  const { url, reconnectDelay = 3000, maxReconnects = Infinity } = options;
+
+  type Callback = (event: LiveEvent) => void;
+  const subscribers = new Map<string, Set<Callback>>();
+  let ws: WebSocket | null = null;
+  let reconnectAttempts = 0;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let status: 'connecting' | 'connected' | 'disconnected' = 'disconnected';
+  let intentionalClose = false;
+
+  function connect() {
+    if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+
+    status = 'connecting';
+    intentionalClose = false;
+
+    try {
+      ws = new WebSocket(url);
+    } catch {
+      status = 'disconnected';
+      scheduleReconnect();
+      return;
+    }
+
+    ws.onopen = () => {
+      status = 'connected';
+      reconnectAttempts = 0;
+      options.onOpen?.();
+    };
+
+    ws.onmessage = (msgEvent) => {
+      try {
+        const event: LiveEvent = JSON.parse(msgEvent.data);
+        if (event.type && event.resource) {
+          const callbacks = subscribers.get(event.resource);
+          if (callbacks) {
+            for (const cb of callbacks) cb(event);
+          }
+          // Also notify wildcard '*' subscribers
+          const wildcardCallbacks = subscribers.get('*');
+          if (wildcardCallbacks) {
+            for (const cb of wildcardCallbacks) cb(event);
+          }
+        }
+      } catch {
+        // ignore non-JSON messages
+      }
+    };
+
+    ws.onclose = (event) => {
+      status = 'disconnected';
+      options.onClose?.(event);
+      if (!intentionalClose) scheduleReconnect();
+    };
+
+    ws.onerror = (event) => {
+      options.onError?.(event);
+    };
+  }
+
+  function scheduleReconnect() {
+    if (reconnectAttempts >= maxReconnects) return;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+
+    reconnectAttempts++;
+    reconnectTimer = setTimeout(connect, reconnectDelay);
+  }
+
+  function disconnect() {
+    intentionalClose = true;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+    status = 'disconnected';
+  }
+
+  // Auto-connect on creation
+  if (typeof WebSocket !== 'undefined') {
+    connect();
+  }
+
+  return {
+    subscribe({ resource, callback }) {
+      if (!subscribers.has(resource)) {
+        subscribers.set(resource, new Set());
+      }
+      subscribers.get(resource)!.add(callback);
+
+      // Ensure connection is open
+      if (status === 'disconnected' && typeof WebSocket !== 'undefined') {
+        connect();
+      }
+
+      return () => {
+        const callbacks = subscribers.get(resource);
+        if (callbacks) {
+          callbacks.delete(callback);
+          if (callbacks.size === 0) subscribers.delete(resource);
+        }
+        // Auto-disconnect if no subscribers left
+        if (subscribers.size === 0) disconnect();
+      };
+    },
+
+    disconnect,
+
+    getStatus() {
+      return status;
+    },
+  };
+}

package/src/live.test.ts

@@ -0,0 +1,134 @@
+/**
+ * LiveProvider unit tests
+ * Tests the subscription management logic without requiring actual WebSocket/SSE connections.
+ */
+import { describe, test, expect, mock } from 'bun:test';
+import type { LiveProvider, LiveEvent } from './live';
+
+// Helper: create a minimal in-memory LiveProvider for testing subscription logic
+function createMockLiveProvider(): LiveProvider & { emit: (event: LiveEvent) => void } {
+  type Callback = (event: LiveEvent) => void;
+  const subscribers = new Map<string, Set<Callback>>();
+
+  return {
+    subscribe({ resource, callback }) {
+      if (!subscribers.has(resource)) {
+        subscribers.set(resource, new Set());
+      }
+      subscribers.get(resource)!.add(callback);
+
+      return () => {
+        const callbacks = subscribers.get(resource);
+        if (callbacks) {
+          callbacks.delete(callback);
+          if (callbacks.size === 0) subscribers.delete(resource);
+        }
+      };
+    },
+
+    emit(event: LiveEvent) {
+      const callbacks = subscribers.get(event.resource);
+      if (callbacks) {
+        for (const cb of callbacks) cb(event);
+      }
+      // Wildcard
+      const wildcardCallbacks = subscribers.get('*');
+      if (wildcardCallbacks) {
+        for (const cb of wildcardCallbacks) cb(event);
+      }
+    },
+  };
+}
+
+describe('LiveProvider subscription', () => {
+  test('subscribe receives events for correct resource', () => {
+    const provider = createMockLiveProvider();
+    const received: LiveEvent[] = [];
+
+    provider.subscribe({
+      resource: 'posts',
+      callback: (event) => received.push(event),
+    });
+
+    provider.emit({ type: 'INSERT', resource: 'posts', payload: { id: 1 } });
+    provider.emit({ type: 'UPDATE', resource: 'comments', payload: { id: 2 } });
+
+    expect(received.length).toBe(1);
+    expect(received[0].type).toBe('INSERT');
+    expect(received[0].resource).toBe('posts');
+  });
+
+  test('wildcard subscriber receives all events', () => {
+    const provider = createMockLiveProvider();
+    const received: LiveEvent[] = [];
+
+    provider.subscribe({
+      resource: '*',
+      callback: (event) => received.push(event),
+    });
+
+    provider.emit({ type: 'INSERT', resource: 'posts', payload: {} });
+    provider.emit({ type: 'DELETE', resource: 'users', payload: {} });
+
+    expect(received.length).toBe(2);
+    expect(received[0].resource).toBe('posts');
+    expect(received[1].resource).toBe('users');
+  });
+
+  test('unsubscribe stops receiving events', () => {
+    const provider = createMockLiveProvider();
+    const received: LiveEvent[] = [];
+
+    const unsub = provider.subscribe({
+      resource: 'posts',
+      callback: (event) => received.push(event),
+    });
+
+    provider.emit({ type: 'INSERT', resource: 'posts', payload: {} });
+    expect(received.length).toBe(1);
+
+    unsub();
+
+    provider.emit({ type: 'UPDATE', resource: 'posts', payload: {} });
+    expect(received.length).toBe(1); // No new events after unsub
+  });
+
+  test('multiple subscribers for same resource', () => {
+    const provider = createMockLiveProvider();
+    const received1: LiveEvent[] = [];
+    const received2: LiveEvent[] = [];
+
+    provider.subscribe({ resource: 'posts', callback: (e) => received1.push(e) });
+    provider.subscribe({ resource: 'posts', callback: (e) => received2.push(e) });
+
+    provider.emit({ type: 'INSERT', resource: 'posts', payload: { id: 1 } });
+
+    expect(received1.length).toBe(1);
+    expect(received2.length).toBe(1);
+  });
+
+  test('LiveEvent types are correct', () => {
+    const insertEvent: LiveEvent = { type: 'INSERT', resource: 'posts', payload: { title: 'New' } };
+    const updateEvent: LiveEvent = { type: 'UPDATE', resource: 'posts', payload: { title: 'Updated' } };
+    const deleteEvent: LiveEvent = { type: 'DELETE', resource: 'posts', payload: { id: 1 } };
+
+    expect(insertEvent.type).toBe('INSERT');
+    expect(updateEvent.type).toBe('UPDATE');
+    expect(deleteEvent.type).toBe('DELETE');
+  });
+
+  test('unsubscribing one does not affect others', () => {
+    const provider = createMockLiveProvider();
+    const received1: LiveEvent[] = [];
+    const received2: LiveEvent[] = [];
+
+    const unsub1 = provider.subscribe({ resource: 'posts', callback: (e) => received1.push(e) });
+    provider.subscribe({ resource: 'posts', callback: (e) => received2.push(e) });
+
+    unsub1();
+    provider.emit({ type: 'INSERT', resource: 'posts', payload: {} });
+
+    expect(received1.length).toBe(0);
+    expect(received2.length).toBe(1);
+  });
+});