@object-ui/core 0.3.1 → 2.0.0

package/src/adapters/ApiDataSource.ts

@@ -0,0 +1,349 @@
+/**
+ * ObjectUI — ApiDataSource
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * A DataSource adapter for the `provider: 'api'` ViewData mode.
+ * Makes raw HTTP requests using the HttpRequest configs from ViewData.
+ */
+
+import type {
+  DataSource,
+  QueryParams,
+  QueryResult,
+  HttpRequest,
+  HttpMethod,
+} from '@object-ui/types';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface ApiDataSourceConfig {
+  /** HttpRequest config for read operations (find, findOne) */
+  read?: HttpRequest;
+  /** HttpRequest config for write operations (create, update, delete) */
+  write?: HttpRequest;
+  /** Custom fetch implementation (defaults to globalThis.fetch) */
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  /** Default headers applied to all requests */
+  defaultHeaders?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build a full URL with query params */
+function buildUrl(
+  base: string,
+  pathSuffix?: string,
+  queryParams?: Record<string, unknown>,
+): string {
+  let url = base;
+  if (pathSuffix) {
+    url = url.replace(/\/+$/, '') + '/' + pathSuffix.replace(/^\/+/, '');
+  }
+
+  if (queryParams && Object.keys(queryParams).length > 0) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryParams)) {
+      if (value !== undefined && value !== null) {
+        search.set(key, String(value));
+      }
+    }
+    const qs = search.toString();
+    if (qs) {
+      url += (url.includes('?') ? '&' : '?') + qs;
+    }
+  }
+
+  return url;
+}
+
+/** Convert QueryParams to flat query string params */
+function queryParamsToRecord(params?: QueryParams): Record<string, unknown> {
+  if (!params) return {};
+
+  const out: Record<string, unknown> = {};
+
+  if (params.$select?.length) {
+    out.$select = params.$select.join(',');
+  }
+  if (params.$filter && Object.keys(params.$filter).length > 0) {
+    out.$filter = JSON.stringify(params.$filter);
+  }
+  if (params.$orderby) {
+    if (Array.isArray(params.$orderby)) {
+      if (typeof params.$orderby[0] === 'string') {
+        out.$orderby = (params.$orderby as string[]).join(',');
+      } else {
+        out.$orderby = (params.$orderby as Array<{ field: string; order?: string }>)
+          .map((s) => `${s.field} ${s.order || 'asc'}`)
+          .join(',');
+      }
+    } else {
+      out.$orderby = Object.entries(params.$orderby)
+        .map(([field, order]) => `${field} ${order}`)
+        .join(',');
+    }
+  }
+  if (params.$skip !== undefined) out.$skip = params.$skip;
+  if (params.$top !== undefined) out.$top = params.$top;
+  if (params.$expand?.length) out.$expand = params.$expand.join(',');
+  if (params.$search) out.$search = params.$search;
+  if (params.$count) out.$count = 'true';
+
+  return out;
+}
+
+/** Merge two header objects, giving priority to the second */
+function mergeHeaders(
+  base?: Record<string, string>,
+  override?: Record<string, string>,
+): Record<string, string> {
+  return { ...base, ...override };
+}
+
+// ---------------------------------------------------------------------------
+// ApiDataSource
+// ---------------------------------------------------------------------------
+
+/**
+ * ApiDataSource — a DataSource adapter for raw HTTP APIs.
+ *
+ * Used when `ViewData.provider === 'api'`. The read and write HttpRequest
+ * configs define the endpoints; all CRUD methods map onto HTTP verbs.
+ *
+ * Read operations use the `read` config, write operations use the `write` config.
+ * Both fall back to each other when one is not provided.
+ *
+ * @example
+ * ```ts
+ * const ds = new ApiDataSource({
+ *   read:  { url: '/api/contacts', method: 'GET' },
+ *   write: { url: '/api/contacts', method: 'POST' },
+ * });
+ *
+ * const result = await ds.find('contacts', { $top: 10 });
+ * ```
+ */
+export class ApiDataSource<T = any> implements DataSource<T> {
+  private readConfig: HttpRequest | undefined;
+  private writeConfig: HttpRequest | undefined;
+  private fetchFn: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  private defaultHeaders: Record<string, string>;
+
+  constructor(config: ApiDataSourceConfig) {
+    this.readConfig = config.read;
+    this.writeConfig = config.write;
+    this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.defaultHeaders = config.defaultHeaders ?? {};
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal request executor
+  // -----------------------------------------------------------------------
+
+  private async request<R = any>(
+    base: HttpRequest | undefined,
+    options: {
+      pathSuffix?: string;
+      method?: HttpMethod;
+      queryParams?: Record<string, unknown>;
+      body?: unknown;
+      headers?: Record<string, string>;
+    } = {},
+  ): Promise<R> {
+    if (!base) {
+      throw new Error(
+        'ApiDataSource: No HTTP configuration provided for this operation. ' +
+          'Ensure the ViewData has read/write configs.',
+      );
+    }
+
+    const method = options.method ?? base.method ?? 'GET';
+
+    // Merge query params: base.params + extra queryParams
+    const allQuery = {
+      ...(base.params as Record<string, unknown> | undefined),
+      ...options.queryParams,
+    };
+
+    const url = buildUrl(base.url, options.pathSuffix, allQuery);
+
+    const headers = mergeHeaders(
+      mergeHeaders(this.defaultHeaders, base.headers),
+      options.headers,
+    );
+
+    const init: RequestInit = {
+      method,
+      headers,
+    };
+
+    // Attach body for non-GET methods
+    if (options.body !== undefined && method !== 'GET') {
+      if (
+        options.body instanceof FormData ||
+        options.body instanceof Blob
+      ) {
+        init.body = options.body as FormData | Blob;
+      } else if (typeof options.body === 'string') {
+        init.body = options.body;
+        if (!headers['Content-Type']) {
+          headers['Content-Type'] = 'text/plain';
+        }
+      } else {
+        init.body = JSON.stringify(options.body);
+        if (!headers['Content-Type']) {
+          headers['Content-Type'] = 'application/json';
+        }
+      }
+    }
+
+    const response = await this.fetchFn(url, init);
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new Error(
+        `ApiDataSource: HTTP ${response.status} ${response.statusText} — ${text}`,
+      );
+    }
+
+    // Try to parse as JSON; fall back to empty object
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+      return response.json();
+    }
+
+    // Non-JSON response — return text wrapped in an object
+    const text = await response.text();
+    return text as unknown as R;
+  }
+
+  // -----------------------------------------------------------------------
+  // DataSource interface
+  // -----------------------------------------------------------------------
+
+  async find(_resource: string, params?: QueryParams): Promise<QueryResult<T>> {
+    const queryParams = queryParamsToRecord(params);
+    const raw = await this.request<any>(this.readConfig, {
+      method: 'GET',
+      queryParams,
+    });
+
+    // Normalize: the API might return an array, an object with `data`, or a QueryResult
+    return this.normalizeQueryResult(raw);
+  }
+
+  async findOne(_resource: string, id: string | number, params?: QueryParams): Promise<T | null> {
+    try {
+      const queryParams = queryParamsToRecord(params);
+      const raw = await this.request<T>(this.readConfig, {
+        pathSuffix: String(id),
+        method: 'GET',
+        queryParams,
+      });
+      return raw ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  async create(_resource: string, data: Partial<T>): Promise<T> {
+    const config = this.writeConfig ?? this.readConfig;
+    return this.request<T>(config, {
+      method: 'POST',
+      body: data,
+    });
+  }
+
+  async update(_resource: string, id: string | number, data: Partial<T>): Promise<T> {
+    const config = this.writeConfig ?? this.readConfig;
+    return this.request<T>(config, {
+      pathSuffix: String(id),
+      method: 'PATCH',
+      body: data,
+    });
+  }
+
+  async delete(_resource: string, id: string | number): Promise<boolean> {
+    const config = this.writeConfig ?? this.readConfig;
+    try {
+      await this.request(config, {
+        pathSuffix: String(id),
+        method: 'DELETE',
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async getObjectSchema(_objectName: string): Promise<any> {
+    // Generic API endpoints typically don't expose schema metadata.
+    // Return a minimal stub so schema-dependent components don't crash.
+    return { name: _objectName, fields: {} };
+  }
+
+  async getView(_objectName: string, _viewId: string): Promise<any | null> {
+    return null;
+  }
+
+  async getApp(_appId: string): Promise<any | null> {
+    return null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Normalize various API response shapes into a QueryResult.
+   *
+   * Supported shapes:
+   * - `T[]`                      → wrap in QueryResult
+   * - `{ data: T[] }`            → extract data
+   * - `{ items: T[] }`           → extract items
+   * - `{ results: T[] }`         → extract results
+   * - `{ records: T[] }`         → extract records (Salesforce-style)
+   * - `{ value: T[] }`           → extract value (OData-style)
+   * - Full QueryResult (has data + totalCount) → return as-is
+   */
+  private normalizeQueryResult(raw: any): QueryResult<T> {
+    if (Array.isArray(raw)) {
+      return { data: raw, total: raw.length };
+    }
+
+    if (raw && typeof raw === 'object') {
+      // Already a QueryResult
+      if (Array.isArray(raw.data) && ('total' in raw || 'totalCount' in raw)) {
+        return {
+          data: raw.data,
+          total: raw.total ?? raw.totalCount ?? raw.data.length,
+          hasMore: raw.hasMore,
+          cursor: raw.cursor,
+        };
+      }
+
+      // Common envelope patterns
+      for (const key of ['data', 'items', 'results', 'records', 'value']) {
+        if (Array.isArray(raw[key])) {
+          return {
+            data: raw[key],
+            total: raw.total ?? raw.totalCount ?? raw.count ?? raw[key].length,
+            hasMore: raw.hasMore ?? raw.hasNextPage,
+          };
+        }
+      }
+
+      // Single-object response — wrap as array
+      return { data: [raw as T], total: 1 };
+    }
+
+    return { data: [], total: 0 };
+  }
+}

package/src/adapters/ValueDataSource.ts

@@ -0,0 +1,332 @@
+/**
+ * ObjectUI — ValueDataSource
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * A DataSource adapter for the `provider: 'value'` ViewData mode.
+ * Operates entirely on an in-memory array — no network requests.
+ */
+
+import type {
+  DataSource,
+  QueryParams,
+  QueryResult,
+} from '@object-ui/types';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface ValueDataSourceConfig<T = any> {
+  /** The static data array */
+  items: T[];
+  /** Optional ID field name for findOne/update/delete (defaults to '_id' then 'id') */
+  idField?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve the ID of a record given possible field names */
+function getRecordId(record: any, idField?: string): string | number | undefined {
+  if (idField) return record[idField];
+  return record._id ?? record.id;
+}
+
+/**
+ * Simple in-memory filter evaluation.
+ * Supports flat key-value equality and basic operators ($gt, $gte, $lt, $lte, $ne, $in).
+ */
+function matchesFilter(record: any, filter: Record<string, any>): boolean {
+  for (const [key, condition] of Object.entries(filter)) {
+    const value = record[key];
+
+    if (condition && typeof condition === 'object' && !Array.isArray(condition)) {
+      // Operator-based filter
+      for (const [op, target] of Object.entries(condition)) {
+        switch (op) {
+          case '$gt':
+            if (!(value > (target as any))) return false;
+            break;
+          case '$gte':
+            if (!(value >= (target as any))) return false;
+            break;
+          case '$lt':
+            if (!(value < (target as any))) return false;
+            break;
+          case '$lte':
+            if (!(value <= (target as any))) return false;
+            break;
+          case '$ne':
+            if (value === target) return false;
+            break;
+          case '$in':
+            if (!Array.isArray(target) || !target.includes(value)) return false;
+            break;
+          case '$contains':
+            if (typeof value !== 'string' || !value.toLowerCase().includes(String(target).toLowerCase())) return false;
+            break;
+          default:
+            break;
+        }
+      }
+    } else {
+      // Simple equality
+      if (value !== condition) return false;
+    }
+  }
+  return true;
+}
+
+/** Apply sort ordering to an array (returns a new sorted array) */
+function applySort<T>(
+  data: T[],
+  orderby?: QueryParams['$orderby'],
+): T[] {
+  if (!orderby) return data;
+
+  // Normalize to array of { field, order }
+  let sorts: Array<{ field: string; order: 'asc' | 'desc' }> = [];
+
+  if (Array.isArray(orderby)) {
+    sorts = orderby.map((item) => {
+      if (typeof item === 'string') {
+        if (item.startsWith('-')) {
+          return { field: item.slice(1), order: 'desc' as const };
+        }
+        return { field: item, order: 'asc' as const };
+      }
+      return { field: item.field, order: (item.order ?? 'asc') as 'asc' | 'desc' };
+    });
+  } else if (typeof orderby === 'object') {
+    sorts = Object.entries(orderby).map(([field, order]) => ({
+      field,
+      order: order as 'asc' | 'desc',
+    }));
+  }
+
+  if (sorts.length === 0) return data;
+
+  return [...data].sort((a: any, b: any) => {
+    for (const { field, order } of sorts) {
+      const av = a[field];
+      const bv = b[field];
+      if (av === bv) continue;
+      if (av == null) return order === 'asc' ? -1 : 1;
+      if (bv == null) return order === 'asc' ? 1 : -1;
+      const cmp = av < bv ? -1 : 1;
+      return order === 'asc' ? cmp : -cmp;
+    }
+    return 0;
+  });
+}
+
+/** Pick specific fields from a record */
+function selectFields<T>(record: T, fields?: string[]): T {
+  if (!fields || fields.length === 0) return record;
+  const out: any = {};
+  for (const f of fields) {
+    if (f in (record as any)) {
+      out[f] = (record as any)[f];
+    }
+  }
+  return out as T;
+}
+
+// ---------------------------------------------------------------------------
+// ValueDataSource
+// ---------------------------------------------------------------------------
+
+/**
+ * ValueDataSource — an in-memory DataSource backed by a static array.
+ *
+ * Used when `ViewData.provider === 'value'`. All operations are synchronous
+ * (but wrapped in Promises to satisfy the DataSource interface). Supports
+ * basic filter, sort, pagination, and CRUD operations.
+ *
+ * @example
+ * ```ts
+ * const ds = new ValueDataSource({
+ *   items: [
+ *     { id: '1', name: 'Alice', age: 30 },
+ *     { id: '2', name: 'Bob', age: 25 },
+ *   ],
+ * });
+ *
+ * const result = await ds.find('users', { $filter: { age: { $gt: 26 } } });
+ * // result.data === [{ id: '1', name: 'Alice', age: 30 }]
+ * ```
+ */
+export class ValueDataSource<T = any> implements DataSource<T> {
+  private items: T[];
+  private idField: string | undefined;
+
+  constructor(config: ValueDataSourceConfig<T>) {
+    // Deep clone to prevent external mutation
+    this.items = JSON.parse(JSON.stringify(config.items));
+    this.idField = config.idField;
+  }
+
+  // -----------------------------------------------------------------------
+  // DataSource interface
+  // -----------------------------------------------------------------------
+
+  async find(_resource: string, params?: QueryParams): Promise<QueryResult<T>> {
+    let result = [...this.items];
+
+    // Filter
+    if (params?.$filter && Object.keys(params.$filter).length > 0) {
+      result = result.filter((r) => matchesFilter(r, params.$filter!));
+    }
+
+    // Search (simple text search across all string fields)
+    if (params?.$search) {
+      const q = params.$search.toLowerCase();
+      result = result.filter((r) =>
+        Object.values(r as any).some(
+          (v) => typeof v === 'string' && v.toLowerCase().includes(q),
+        ),
+      );
+    }
+
+    const totalCount = result.length;
+
+    // Sort
+    result = applySort(result, params?.$orderby);
+
+    // Pagination
+    const skip = params?.$skip ?? 0;
+    const top = params?.$top;
+    if (skip > 0) result = result.slice(skip);
+    if (top !== undefined) result = result.slice(0, top);
+
+    // Select
+    if (params?.$select?.length) {
+      result = result.map((r) => selectFields(r, params.$select));
+    }
+
+    return {
+      data: result,
+      total: totalCount,
+      hasMore: skip + (top ?? result.length) < totalCount,
+    };
+  }
+
+  async findOne(
+    _resource: string,
+    id: string | number,
+    params?: QueryParams,
+  ): Promise<T | null> {
+    const record = this.items.find(
+      (r) => String(getRecordId(r, this.idField)) === String(id),
+    );
+    if (!record) return null;
+
+    if (params?.$select?.length) {
+      return selectFields(record, params.$select);
+    }
+    return { ...record };
+  }
+
+  async create(_resource: string, data: Partial<T>): Promise<T> {
+    const record = { ...data } as T;
+    // Auto-generate an ID if missing
+    if (!getRecordId(record, this.idField)) {
+      const field = this.idField ?? '_id';
+      (record as any)[field] = `auto_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    }
+    this.items.push(record);
+    return { ...record };
+  }
+
+  async update(
+    _resource: string,
+    id: string | number,
+    data: Partial<T>,
+  ): Promise<T> {
+    const index = this.items.findIndex(
+      (r) => String(getRecordId(r, this.idField)) === String(id),
+    );
+    if (index === -1) {
+      throw new Error(`ValueDataSource: Record with id "${id}" not found`);
+    }
+    this.items[index] = { ...this.items[index], ...data };
+    return { ...this.items[index] };
+  }
+
+  async delete(_resource: string, id: string | number): Promise<boolean> {
+    const index = this.items.findIndex(
+      (r) => String(getRecordId(r, this.idField)) === String(id),
+    );
+    if (index === -1) return false;
+    this.items.splice(index, 1);
+    return true;
+  }
+
+  async bulk(
+    _resource: string,
+    operation: 'create' | 'update' | 'delete',
+    data: Partial<T>[],
+  ): Promise<T[]> {
+    const results: T[] = [];
+    for (const item of data) {
+      switch (operation) {
+        case 'create':
+          results.push(await this.create(_resource, item));
+          break;
+        case 'update': {
+          const id = getRecordId(item, this.idField);
+          if (id !== undefined) {
+            results.push(await this.update(_resource, id, item));
+          }
+          break;
+        }
+        case 'delete': {
+          const id = getRecordId(item, this.idField);
+          if (id !== undefined) {
+            await this.delete(_resource, id);
+          }
+          break;
+        }
+      }
+    }
+    return results;
+  }
+
+  async getObjectSchema(_objectName: string): Promise<any> {
+    // Infer a minimal schema from the first item
+    if (this.items.length === 0) return { name: _objectName, fields: {} };
+
+    const sample = this.items[0];
+    const fields: Record<string, any> = {};
+    for (const [key, value] of Object.entries(sample as any)) {
+      fields[key] = { type: typeof value };
+    }
+    return { name: _objectName, fields };
+  }
+
+  async getView(_objectName: string, _viewId: string): Promise<any | null> {
+    return null;
+  }
+
+  async getApp(_appId: string): Promise<any | null> {
+    return null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Extra utilities
+  // -----------------------------------------------------------------------
+
+  /** Get the current number of items */
+  get count(): number {
+    return this.items.length;
+  }
+
+  /** Get a snapshot of all items (cloned) */
+  getAll(): T[] {
+    return JSON.parse(JSON.stringify(this.items));
+  }
+}