@happyvertical/smrt-features

npm install @happyvertical/smrt-features

import {
  FeatureResolver,
  FeatureSyncService,
  FeatureOverrideCollection,
  FeatureOverrideEffect,
  createFeatureKey,
} from '@happyvertical/smrt-features';

// 1. Sync definitions to DB at boot.
// Definitions are read from the SMRT ObjectRegistry (features declared on
// @smrt()-decorated classes), not from a literal array. With no filter,
// syncDefinitions() reconciles every registered feature.
const sync = new FeatureSyncService({ db });
const result = await sync.syncDefinitions();
// result: { total, created, updated, unchanged, deleted, featureKeys }

// 2. Resolve a feature for the current context (returns a boolean).
// Feature keys are "<qualifiedClassName>#<localId>".
const resolver = new FeatureResolver({ db });
const featureKey = createFeatureKey('@acme/commerce:Invoice', 'draftMode');
const enabled = await resolver.isEnabled(featureKey, {
  tenantId: 'tenant-123',
});

// Or resolve directly from a class/instance + localId:
// await resolver.isEnabledFor(Invoice, 'draftMode', { tenantId });

// 3. Write a tenant-level override via FeatureOverrideCollection.
const overrides = await FeatureOverrideCollection.create({ db });
await overrides.setOverride(
  featureKey,
  'tenant',
  'tenant-123',
  FeatureOverrideEffect.ENABLE,
);

Resolution order
  1. Definition default (defaultEnabled on the code-registered FeatureDefinition)
  2. Global override   scopeType: 'global', scopeId: GLOBAL_FEATURE_SCOPE_ID ('*')
  3. Tenant override   scopeType: 'tenant', scopeId: tenantId
                       (walks root -> ... -> tenantId via smrt-users, applying
                        each override down the chain)

Override effects: 'enable' | 'disable' | 'inherit' (FeatureOverrideEffect).
'inherit' leaves the inherited state unchanged.

There is no per-user scope: scopeType is 'global' or 'tenant' only.
The tenant-hierarchy walk requires the @happyvertical/smrt-users peer.
Without it (or without a tenantId), tenant resolution uses the single
direct tenant override.

class FeatureDefinition extends SmrtObject {
  featureKey: string           // '<qualifiedClassName>#<localId>'
  packageName: string          // owning package
  qualifiedClassName: string   // e.g. '@acme/commerce:Invoice'
  className: string
  localId: string              // the feature id within the class
  defaultEnabled: boolean      // default state when no override matches
  label: string
  description: string
  metadata: string             // JSON metadata stored as text (get/setMetadata)
  visibility: string           // default 'public'

  // System table: _smrt_feature_definitions (conflictColumns: ['feature_key'])
  // Owned by code via FeatureSyncService — do not write directly
}

enum FeatureOverrideEffect {
  INHERIT = 'inherit',
  ENABLE = 'enable',
  DISABLE = 'disable',
}

class FeatureOverride extends SmrtObject {
  featureKey: string
  scopeType: 'global' | 'tenant'         // no 'user' scope
  scopeId: string                        // tenantId, or GLOBAL_FEATURE_SCOPE_ID ('*')
  effect: FeatureOverrideEffect          // default INHERIT

  // Helpers: isInherit(), isEnabled(), isDisabled()
  // System table: _smrt_feature_overrides
  // conflictColumns: ['feature_key', 'scope_type', 'scope_id']
}

const sync = new FeatureSyncService({ db });

// Full reconcile of every registered feature
const result = await sync.syncDefinitions();

// Or scope to specific classes (pruneStale defaults to false here)
await sync.syncDefinitions({ classNames: ['Invoice', 'Order'] });

// result: { total, created, updated, unchanged, deleted, featureKeys }
// - Upserts definitions for registered features (created / updated / unchanged)
// - On a full sync, deletes definitions whose feature keys are no longer registered

// You can also sync directly from a manifest:
// await sync.syncManifest(manifest, { pruneStale: true });