Dcupl class API

constructor(options?: DcuplInitOptions): Dcupl

const dcupl = new Dcupl();

const dcupl = new Dcupl<'Product' | 'Category'>();
dcupl.models.get('Product'); // ok
dcupl.data.reset({ model: 'Prodcut' }); // compile error: not a model key

const dcupl = new Dcupl({
  config: {
    projectId: 'your-project-id',
    apiKey: 'your-api-key',
    version: 'draft',
  },
});

const dcupl = new Dcupl({
  quality: {
    enabled: true, // default
    maxErrorsPerGroup: 1000, // default
  },
});

const dcupl = new Dcupl({
  performance: {
    cache: {
      enabled: true, // default
    },
  },
});

const dcupl = new Dcupl({
  performance: {
    autoUpdateLists: {
      enabled: true,
    },
  },
});

const model = dcupl.models.get('Product');

const list = dcupl.lists.create({ modelKey: 'Product' });

dcupl.data.set(products, { model: 'Product' });

const items = dcupl.query.execute({
  modelKey: 'Product',
  queries: [{ operator: 'eq', attribute: 'status', value: 'active' }],
});

const facets = dcupl.fn.facets({
  modelKey: 'Product',
  options: { attribute: 'category' },
});

// Section View - for groupBy operations
type ViewDefinitionSection = {
  key: string;
  model: string;
  type: 'section';
  primaryAttribute: string;
  aggregates: AggregationOptions[];
};

// Pivot View - for pivot table operations
type ViewDefinitionPivot = {
  key: string;
  model: string;
  type: 'pivot';
  options: PivotOptions;
};

// Register a section view
dcupl.views.set({
  key: 'productsByCategory',
  model: 'Product',
  type: 'section',
  primaryAttribute: 'category',
  aggregates: [{ attribute: 'price', types: ['sum', 'avg'] }],
});

// Register a pivot view
dcupl.views.set({
  key: 'salesPivot',
  model: 'Order',
  type: 'pivot',
  options: {
    rows: [{ attribute: 'region' }],
    columns: [{ attribute: 'quarter' }],
    values: [{ attribute: 'revenue', types: ['sum'] }],
  },
});

// Get a view
const view = dcupl.views.get('productsByCategory');

// Get all view keys for a model
const productViews = dcupl.views.keys({ modelKey: 'Product' });

// Register a synchronous script
dcupl.scripts.set(
  'calculateTotal',
  `
  const list = dcupl.lists.get('cart');
  const items = list.catalog.query.items();
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
`,
);

// Execute synchronously
const total = dcupl.scripts.execute('calculateTotal');

// Register an async script
dcupl.scripts.set(
  'fetchAndUpdate',
  `
  fetch('/api/products')
    .then(res => res.json())
    .then(async data => {
      dcupl.data.set(data, { model: 'Product' });
      await dcupl.update(); // apply the staged data
      resolve({ updated: data.length });
    })
    .catch(reject);
`,
);

// Execute asynchronously
const result = await dcupl.scripts.executeAsync('fetchAndUpdate');

// Pass options to script
dcupl.scripts.set(
  'filterByCategory',
  `
  const list = dcupl.lists.get('products');
  list.catalog.query.addCondition({
    attribute: 'category',
    operator: 'eq',
    value: options.category,
  });
  return list.catalog.query.items();
`,
);

const electronics = dcupl.scripts.execute('filterByCategory', { category: 'Electronics' });

// Run a script as an endpoint: `dcupl` is read-only, the return value is the response body
dcupl.scripts.set(
  'product-count',
  `
  if (script_type !== 'endpoint') throw new Error('unsupported script type: ' + script_type);
  const items = dcupl.query.execute({
    modelKey: 'Product',
    queries: [{ attribute: 'category', operator: 'eq', value: request.query.category }],
  });
  return { count: items.length };
`,
);

const body = await dcupl.scripts.executeEndpoint('product-count', {
  method: 'GET',
  path: 'product-count',
  params: {},
  query: { category: 'Electronics' },
  body: undefined,
  headers: {},
});

// List all scripts
const scriptKeys = dcupl.scripts.keys();

// Remove a script
dcupl.scripts.remove('filterByCategory');

import { Dcupl } from '@dcupl/core';
import { DcuplAppLoader } from '@dcupl/loader';

const dcupl = new Dcupl({
  config: { projectId: 'my-project', apiKey: 'my-api-key' },
});

// Register the loader first: it takes projectId/apiKey from dcupl
const loader = new DcuplAppLoader();
dcupl.loaders.add(loader, 'main');

// Fetch the configuration, load the resources, then initialize
await loader.config.fetch();
await loader.process(); // loads every resource; see /sdk/api/loader#applications
await dcupl.init();

// Access loader later
const mainLoader = dcupl.loaders.get('main');

// Totals per (model, attribute, errorType)
for (const group of dcupl.quality.errors.summary()) {
  console.log(group.key, group.totalCount); // key: 'Model::attribute::ErrorType'
}

// Individual error records
const userErrors = dcupl.query.execute({
  modelKey: '$DcuplErrorTrackingErrors',
  queries: [{ attribute: 'model', operator: 'eq', value: 'User' }],
});

console.log(dcupl.initOptions.performance?.cache?.enabled);

async init(): Promise<boolean>

await dcupl.init();

const success = await dcupl.init();
if (!success) {
  console.error('Initialization failed');
}

const dcupl = new Dcupl();
dcupl.models.set({
  key: 'Product',
  properties: [
    { key: 'name', type: 'string' },
    { key: 'price', type: 'float' },
  ],
});
dcupl.data.set(products, { model: 'Product' });
await dcupl.init();

async update(options?: DcuplUpdateOptions): Promise<boolean>

await dcupl.update();

await dcupl.update({ autoUpdateLists: true });

await dcupl.update({ autoUpdateLists: false });

dcupl.data.update([{ key: 'p1', name: 'Updated Product' }], { model: 'Product' });
await dcupl.update();

dcupl.data.update(batch1, { model: 'Product' });
dcupl.data.update(batch2, { model: 'Category' });
await dcupl.update(); // Processes both batches

destroy(): void

dcupl.destroy();

const dcupl = new Dcupl();
await dcupl.init();
// ... use dcupl
dcupl.destroy();

seal(): void

const dcupl = new Dcupl({ performance: { retainStagedData: false } });
await loader.process();
await dcupl.init(); // builds the models, then drops the staged rows
dcupl.sealed; // true

import { DcuplSealedError } from '@dcupl/common';

await dcupl.init();
dcupl.seal();
try {
  dcupl.data.update([{ key: 'p1', price: 9 }], { model: 'Product' });
} catch (err) {
  if (err instanceof DcuplSealedError) console.log(err.what, err.message);
}

on(callback: CallbackFunction): () => void

const unsubscribe = dcupl.on((message) => {
  console.log('Change detected:', message);
});

unsubscribe();

dcupl.on((message) => {
  if (message.type === 'dcupl_updated_manually') {
    console.log('Data was updated');
  }
  if (message.type === 'dcupl_partial_update') {
    console.log('Changed models:', message.args[0].changedModels);
  }
});

const unsub1 = dcupl.on(callback1);
const unsub2 = dcupl.on(callback2);

// Cleanup all
unsub1();
unsub2();

type DcuplInitOptions = {
  config?: DcuplInitConfig;
  quality?: DcuplInitQualityConfig;
  performance?: DcuplInitPerformanceConfig;
  analytics?: DcuplInitErrorAnalyticsConfig;
  referenceMetadata?: DcuplInitReferenceMetadataConfig;
  logging?: DcuplInitLoggingConfig;
  scripting?: DcuplInitScriptingConfig;
  /** @deprecated use `quality` */
  errorTracking?: { enabled: boolean };
};

type DcuplInitConfig = {
  projectId?: string;
  apiKey?: string;
  version?: string; // default 'draft'
};

const dcupl = new Dcupl({
  config: {
    projectId: 'my-project',
    apiKey: 'readonly-key',
    version: 'v1.0.0',
  },
});

type DcuplInitQualityConfig = {
  enabled: boolean; // default true
  maxErrorsPerGroup?: number; // default 1000
};

const dcupl = new Dcupl({
  quality: {
    enabled: true,
  },
});

type DcuplInitPerformanceConfig = {
  cache?: {
    enabled: boolean;
    maxSize?: number; // estimated bytes, default 64 MiB; Infinity = no limit
    maxProjectionSize?: number; // estimated bytes per list, default 256 MiB; Infinity = no limit
  };
  clone?: {
    enabled: boolean;
  };
  partialUpdates?: DcuplPartialUpdateConfig;
  containerBatchSize?: number;
  autoUpdateLists?: {
    enabled: boolean;
  };
  retainStagedData?: boolean; // default true; false seals the instance after init()
};

const dcupl = new Dcupl({
  performance: {
    cache: { enabled: true },
  },
});

const dcupl = new Dcupl({
  performance: {
    partialUpdates: {
      modelRatioThreshold: 0.5,
      itemRatioThreshold: 0.5,
      enableDetailedLogging: true,
    },
  },
});

const dcupl = new Dcupl({
  performance: {
    autoUpdateLists: { enabled: true },
  },
});

type DcuplPartialUpdateConfig = {
  modelRatioThreshold?: number;
  itemRatioThreshold?: number;
  enableDetailedLogging?: boolean;
};

type DcuplUpdateOptions = {
  autoUpdateLists?: boolean;
};

await dcupl.update({ autoUpdateLists: true });

await dcupl.update({ autoUpdateLists: false });

type DcuplInitLoggingConfig = {
  level?: LogLevel;
  format?: 'json' | 'pretty';
  onLog?: (entry: LogEntry) => void;
  modules?: Record<string, LogLevel>;
};

import { Dcupl } from '@dcupl/core';

// Create instance
const dcupl = new Dcupl();

// Define model
dcupl.models.set({
  key: 'Product',
  properties: [
    { key: 'name', type: 'string' },
    { key: 'price', type: 'float' },
    { key: 'status', type: 'string' },
  ],
});

// Add data
dcupl.data.set(
  [
    { key: 'p1', name: 'Product 1', price: 100, status: 'active' },
    { key: 'p2', name: 'Product 2', price: 200, status: 'active' },
  ],
  { model: 'Product' },
);

// Initialize
await dcupl.init();

// Query data
const products = dcupl.query.execute({
  modelKey: 'Product',
  queries: [{ operator: 'eq', attribute: 'status', value: 'active' }],
});

const dcupl = new Dcupl({
  config: {
    projectId: 'my-project',
    apiKey: 'my-api-key',
    version: 'v1.0.0',
  },
  quality: {
    enabled: true,
  },
  performance: {
    cache: {
      enabled: true,
    },
    clone: {
      enabled: true,
    },
    partialUpdates: {
      modelRatioThreshold: 0.5,
      itemRatioThreshold: 0.5,
      enableDetailedLogging: false,
    },
    autoUpdateLists: {
      enabled: true,
    },
  },
});

// Initial setup
await dcupl.init();

// Update single item
dcupl.data.update([{ key: 'p1', price: 150 }], { model: 'Product' });
await dcupl.update();

// Batch updates
dcupl.data.update(batch1, { model: 'Product' });
dcupl.data.update(batch2, { model: 'Category' });
await dcupl.update();

// Re-run query-scoped lists in this update
await dcupl.update({ autoUpdateLists: true });

const unsubscribe = dcupl.on((message) => {
  console.log('Event type:', message.type);
  console.log('Scope:', message.scope);

  if (message.type === 'dcupl_partial_update') {
    const changeInfo = message.args[0];
    console.log('Changed models:', changeInfo.changedModels);
    console.log('Affected models:', changeInfo.affectedModels);
  }
});

unsubscribe();

const productsCore = new Dcupl();
productsCore.models.set(productModel);
await productsCore.init();

const ordersCore = new Dcupl();
ordersCore.models.set(orderModel);
await ordersCore.init();