DcuplAppLoader API

npm install @dcupl/loader

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

const dcupl = new Dcupl();
const loader = new DcuplAppLoader();

// Fetch configuration from dcupl Console
await loader.config.fetch({
  projectId: 'my-project',
  apiKey: 'my-api-key',
});

// Register loader with dcupl
dcupl.loaders.add(loader, 'main');

// Initialize (processes all loaders)
await dcupl.init();

type FetchOptions = {
  projectId?: string;      // dcupl Console project ID
  apiKey?: string;         // dcupl API key
  baseUrl?: string;        // Custom base URL (default: dcupl CDN)
  loaderFileName?: string; // Custom config filename
  headers?: HeadersInit;   // Custom headers for fetch
  skipApply?: boolean;     // Return config without applying
};

// Fetch from dcupl Console
await loader.config.fetch({
  projectId: 'my-project',
  apiKey: 'my-api-key',
});

// Fetch from custom URL
await loader.config.fetch({
  baseUrl: 'https://my-cdn.example.com/config',
  loaderFileName: 'dcupl.loader.json',
});

// Get current config
const config = loader.config.get();
console.log(config?.resources.length);

// Set config manually
loader.config.set({
  resources: [
    { key: 'products', type: 'data', url: '/data/products.json', model: 'Product' },
  ],
  models: [
    { key: 'Product', properties: [{ key: 'name', type: 'string' }] },
  ],
});

type Resource = {
  key: string;
  type: 'model' | 'data' | 'transformer' | 'operator' | 'script';
  url: string;
  model?: string;        // For 'data' type: target model
  tags?: string[];       // For filtering resources
  updateType?: 'set' | 'update' | 'upsert' | 'remove';
  csvParserOptions?: {
    delimiter?: string;
    quoteChar?: string;
    escapeChar?: string;
    commentChar?: string;
  };
};

// Get all resources
const resources = loader.resources.getAll();

// Get resources by tag
const criticalResources = loader.resources.getWithTag('critical');

// Add a new data resource
loader.resources.add({
  key: 'products-update',
  type: 'data',
  url: '/api/products/latest',
  model: 'Product',
  updateType: 'upsert',
  tags: ['live-data'],
});

// Delete a resource
loader.resources.delete('products-update');

// Default variables (from config defaults)
loader.variables.default.get(key);
loader.variables.default.getAll();

// Environment variables (from config environments)
loader.variables.environment.get(env, key);
loader.variables.environment.getAll(env);

// Process variables (passed during processing)
loader.variables.process.get(key);
loader.variables.process.getAll();

// Global variables (set at runtime)
loader.variables.global.get(key);
loader.variables.global.getAll();
loader.variables.global.set(key, value);
loader.variables.global.delete(key);

// Get API URL variable
const apiUrl = loader.variables.get('API_URL');
console.log(apiUrl?.value);

// Get all variables for production environment
const prodVars = loader.variables.getAll('production');

// Get variables as object for easy access
const vars = loader.variables.getAllAsObject('production');
console.log(vars.API_URL);

// Set global variable at runtime
loader.variables.global.set('AUTH_TOKEN', 'Bearer xyz');

// Use in resource URLs with interpolation
// URL: "{{API_URL}}/products" becomes "https://api.example.com/products"

type Transformer = {
  key: string;
  applyTo: string[];  // Resource keys to apply to
  fn: (data: any[], context: TransformerContext) => any[];
};

// Register a transformer to normalize data
loader.transformers.set({
  key: 'normalize-prices',
  applyTo: ['products-csv'],
  fn: (data, context) => {
    return data.map(item => ({
      ...item,
      price: parseFloat(item.price) || 0,
      currency: item.currency || 'USD',
    }));
  },
});

// Get transformers for a resource
const productTransformers = loader.transformers.get({
  applyTo: ['products-csv'],
});

// Remove a transformer
loader.transformers.remove('normalize-prices');

await loader.process(options?: ProcessOptions);

type ProcessOptions = {
  applicationKey?: string;  // Select specific application preset
  environmentKeys?: string[]; // Select environment configurations
  resourceTags?: string[];  // Filter resources by tags
  variables?: Record<string, any>; // Override variables
  options?: {
    defaultDataContainerUpdateType?: 'set' | 'update' | 'upsert';
    csvParserOptions?: CSVParserOptions;
  };
};

// Process with specific environment
await loader.process({
  environmentKeys: ['production'],
});

// Process only tagged resources
await loader.process({
  resourceTags: ['critical', 'models'],
});

// Process with variable overrides
await loader.process({
  variables: {
    API_URL: 'https://staging-api.example.com',
  },
});

const unsubscribe = loader.on((progress: ProgressEvent) => {
  console.log(`${progress.loaded}/${progress.total} resources loaded`);
});

// Later: unsubscribe
unsubscribe();

type ProgressEvent = {
  type: 'resource_loading' | 'resource_loaded' | 'resource_error';
  resourceKey: string;
  loaded: number;
  total: number;
  error?: Error;
};

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

async function initializeDcupl() {
  const dcupl = new Dcupl();
  const loader = new DcuplAppLoader();

  // Track progress
  loader.on((progress) => {
    console.log(`Loading: ${progress.resourceKey} (${progress.loaded}/${progress.total})`);
  });

  // Fetch configuration
  await loader.config.fetch({
    projectId: process.env.DCUPL_PROJECT_ID,
    apiKey: process.env.DCUPL_API_KEY,
  });

  // Add custom transformer
  loader.transformers.set({
    key: 'add-computed-fields',
    applyTo: ['products'],
    fn: (data) => data.map(item => ({
      ...item,
      displayName: `${item.brand} ${item.name}`,
    })),
  });

  // Set runtime variables
  loader.variables.global.set('USER_LOCALE', navigator.language);

  // Process with production config
  await loader.process({
    environmentKeys: ['production'],
  });

  // Register with dcupl
  dcupl.loaders.add(loader, 'main');

  // Initialize
  await dcupl.init();

  return dcupl;
}