@bernierllc/nevar-rule-seeder

Idempotent rule seeder for the Nevar rules engine. Loads default rule groups and rules from configuration into storage using configurable strategies.

Installation

npm install @bernierllc/nevar-rule-seeder

Usage

import { RuleSeeder } from '@bernierllc/nevar-rule-seeder';
import { InMemoryStorageAdapter } from '@bernierllc/nevar-storage';

const storage = new InMemoryStorageAdapter();
const seeder = new RuleSeeder(storage);

const result = await seeder.seed(
  {
    groups: [
      {
        slug: 'onboarding-rules',
        name: 'Onboarding Rules',
        isActive: true,
        rules: [
          {
            name: 'Welcome Email',
            slug: 'welcome-email',
            triggerType: 'user.created',
            conditions: { operator: 'AND', conditions: [] },
            actions: [
              {
                actionType: 'send-email',
                config: { template: 'welcome' },
                executionOrder: 1,
              },
            ],
            executionOrder: 1,
          },
        ],
      },
    ],
  },
  { strategy: 'update_existing', matchBy: 'slug' },
);

console.log(result);
// { groupsCreated: 1, groupsUpdated: 0, groupsSkipped: 0,
//   rulesCreated: 1, rulesUpdated: 0, rulesSkipped: 0, rulesDeleted: 0 }

Seed Strategies

• skip_existing - Create new groups/rules, skip any that already exist (matched by slug or id)
• update_existing - Create new groups/rules, update any that already exist with the seed data
• replace_all - Delete all existing groups and rules, then create everything from the seed data

API

RuleSeeder

Idempotent seeder that loads groups and rules into a storage adapter.

• constructor(storage: StorageForSeeding) - Create a seeder with a storage adapter
• seed(data: SeedData, options: SeedOptions): Promise<SeedResult> - Seed groups and rules according to the given strategy

SeedData (type)

Top-level seed input: { groups: SeedGroupData[] }.

SeedGroupData (type)

Group definition for seeding: slug, name, rules, and optional isDefault, isActive, metadata.

SeedRuleData (type)

Rule definition for seeding: name, slug, triggerType, conditions, actions, executionOrder, and optional isActive, stopOnMatch, allowLoop, logLevel, metadata.

SeedOptions (type)

Controls seeding behavior: { strategy: 'skip_existing' | 'update_existing' | 'replace_all'; matchBy: 'slug' | 'id' }.

SeedResult (type)

Reports what changed: counts for groupsCreated, groupsUpdated, groupsSkipped, rulesCreated, rulesUpdated, rulesSkipped, rulesDeleted.

StorageForSeeding (interface)

Minimal storage interface required for seeding. Subset of NevarStorageAdapter covering group and rule CRUD operations.

NevarSeedError

Custom error class thrown on seed failures. Chains the original error via cause.

Integration Documentation

Logger Integration

This package supports optional integration with @bernierllc/logger for structured logging. Service packages that use the seeder should log seed results and failures through logger for observability into rule provisioning.

NeverHub Integration

This package supports optional integration with @bernierllc/neverhub-adapter. When NeverHub is available, seeding operations can be registered for discovery and monitoring, providing visibility into rule provisioning across environments. Graceful degradation is supported when NeverHub is not present.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.