@happyvertical/smrt-features

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 2.1万

Code-first feature flags and tenant-aware overrides for the SMRT framework

原始使用文档
文档目录11 节
  1. Installation
  2. Quick start
  3. Resolution
  4. Plan grants and paid features
  5. Storage
  6. Generated surfaces
  7. Management UI
  8. Consumer recipe
  9. What the consumer still owns
  10. Feature keys are persisted identifiers
  11. Documentation

@happyvertical/smrt-features

Code-first feature flags for s-m-r-t applications, with global and tenant-hierarchy resolution.

Installation

pnpm add @happyvertical/smrt-features

Quick start

Declare features on their owning class. Import that class before syncing or resolving it. Supply dbOptions for your migrated application database and currentTenantId from your authenticated server context.

import { SmrtObject, smrt } from '@happyvertical/smrt-core';
import {
  FeatureResolver,
  FeatureSyncService,
} from '@happyvertical/smrt-features';

@smrt({
  packageName: '@your/app',
  features: {
    drafts: {
      defaultEnabled: false,
      label: 'Invoice drafts',
      description: 'Save invoices as drafts before sending.',
    },
  },
})
export class Invoice extends SmrtObject {}

const sync = new FeatureSyncService(dbOptions);
await sync.syncDefinitions({ constructors: [Invoice] });

// This example uses flat tenant resolution.
const resolver = new FeatureResolver(dbOptions, {
  tenantHierarchyLoader: async () => null,
});
const enabled = await resolver.isEnabledFor(Invoice, 'drafts', {
  tenantId: currentTenantId,
});
// Equivalent key-based lookup:
const enabledByKey = await resolver.isEnabled('@your/app:Invoice#drafts', {
  tenantId: currentTenantId,
});

Keys have the form <qualifiedClassName>#<localId>. The example's key is @your/app:Invoice#drafts. syncDefinitions() takes optional classNames, constructors, and pruneStale options; a filtered sync never prunes sibling class definitions. An unfiltered sync uses all registered classes and prunes stale definitions in touched packages by default. syncManifest() separately accepts a s-m-r-t SmartObjectManifest containing class decorator metadata.

Resolution

The resolver starts with the registered class's defaultEnabled (falling back to the synced definition), then applies the tenant's plan grant (see below), the global override, and tenant overrides, in that order. Without a tenant context, only the global override applies. explain() returns the same answer as isEnabled() plus decidedBy, the layer that set it (default, plan_grant, global_override or tenant_override).

The default hierarchy loader discovers @happyvertical/smrt-users when available. Alternatively, supply tenantHierarchyLoader as the resolver's second constructor argument; return a FeatureTenantHierarchyProvider or null for flat tenant resolution. Hierarchy traversal runs root to leaf: a child inherits its parent's state only when the parent has cascadePermissions and the child has inheritPermissions; otherwise its baseline resets to the global state (the plan grant with the global override applied). Each tenant's own override then applies. inherit preserves that baseline. Supported scopes are global and tenant.

Plan grants and paid features

A tenant's subscription plan can grant feature keys. A granted key is on for that tenant, and an ungranted key keeps its default. The global override then applies on top: a global row is an explicit operator act, so a global DISABLE stops the feature for every tenant, granted or not. Tenant overrides apply last and beat both the grant and the global override. Features does not depend on @happyvertical/smrt-subscriptions; it consults a FeatureGrantSource, and with none registered (a local install) there are no grants.

The standard paid keys are exported as constants and all default off: FEATURE_SYNC_DEVICES, FEATURE_BACKUP_VAULT, FEATURE_CLOUD_HOSTED, FEATURE_INFERENCE_HOSTED, FEATURE_PLUGINS_REMOTE.

import { FEATURE_SYNC_DEVICES, FeatureResolver, featureGateResponse, requireFeature } from '@happyvertical/smrt-features';
import { SubscriptionFeatureSource } from '@happyvertical/smrt-subscriptions';

// Once per request.
const grantSource = await SubscriptionFeatureSource.create(dbOptions);
const resolver = new FeatureResolver(dbOptions);

// SvelteKit +server.ts: a structured 403 naming the key and the reason.
const denied = await featureGateResponse(FEATURE_SYNC_DEVICES, { resolver, tenantId, grantSource });
if (denied) return denied;

// Services: throws FeatureUnavailableError (status 403, .code, .denial, .toResponse()).
await requireFeature(FEATURE_SYNC_DEVICES, { resolver, tenantId, grantSource });

A denial body has code: 'feature_upgrade_required' with the grantingPlan when the plan is what is missing, or code: 'feature_disabled' with disabledBy (global_override or tenant_override) and no plan when an override turned the feature off, since no upgrade would help.

The gate checks only that the feature is present for the tenant; authenticate the caller and check its permissions first, and pass the tenant you verified. Register an app-wide source with setFeatureGrantSource() instead of passing one per call. defineFrameworkFeature() adds your own dotted keys, and FeatureSyncService.syncFrameworkDefinitions() stores them for the settings screen.

Storage

  • _smrt_feature_definitions — code-owned class identity, local id, boolean default, label, description, and metadata
  • _smrt_feature_overrides — runtime override keyed by feature key, scope type, and scope id

Generated surfaces

FeatureDefinition and FeatureOverride ship with generated REST routes, MCP tools, and CLI commands closed (api: false, mcp: false, cli: false). Override rows are authorization state for every scope, so write them only from server code through FeatureOverrideService, which asks an authorizer you bind to the current caller before every write and fails closed:

const service = new FeatureOverrideService(overrides, (request) =>
  request.scopeType === 'tenant' && request.scopeId === session.tenantId &&
  session.permissions.has('features.manage'),
);
await service.setOverride(key, 'tenant', session.tenantId, FeatureOverrideEffect.ENABLE);

Management UI

The package ships the settings screen so consuming apps do not each rebuild it: FeatureSettingsService (root export) produces the rows, and FeatureSettingsPanel (the ./svelte subpath) renders them. The root export stays Svelte-free, so a server-only consumer is unaffected; svelte is an optional peer dependency.

Consumer recipe

1. Declare the definitions in code. Feature toggles are declared on the @smrt() decorator of the class they belong to:

@smrt({
  features: {
    drafts: { defaultEnabled: false, label: 'Invoice drafts', description: 'Save invoices as drafts before sending.' },
  },
})
export class Invoice extends SmrtObject {}

2. Sync them at startup, so _smrt_feature_definitions matches code:

await new FeatureSyncService(dbOptions).syncDefinitions();

3. Load the rows in your server load. The load is where your permission check lives — the package makes no authorization decision:

// src/routes/settings/features/+page.server.ts
export async function load(event) {
  const auth = requirePermission(event, APP_PERMISSIONS.tenantAdmin);
  const settings = await FeatureSettingsService.create(dbOptions);
  return {
    tenantId: auth.tenantId,
    features: await settings.listFeatureSettings({
      tenantId: auth.tenantId,
      packageName: '@your/app',
    }),
  };
}

listFeatureSettings() returns one FeatureSettingsRow per definition — the definition fields, effectiveEnabled as FeatureResolver resolves it for that tenant, and globalEffect / tenantEffect for the raw override row at each level. The row is structurally assignable to the panel's FeatureSettingsView, so no mapping step is needed.

4. Render the panel:

<script lang="ts">
  import { FeatureSettingsPanel } from '@happyvertical/smrt-features/svelte';
  let { data, form } = $props();
</script>

<FeatureSettingsPanel
  features={data.features}
  tenantLabel="Shop"
  contextKey={data.tenantId}
  formAction="?/saveFeature"
  message={form?.message}
  error={form?.error}
/>

The panel is presentational: it takes rows and callbacks, fetches nothing and authorizes nothing. Each row renders label, description, key, effective state and a Default / Enable / Disable control, where Default removes the override row and returns the feature to whatever the level above resolves to. Pass showGlobal (and globalEditable) only if your app has a platform-admin tier; apps without one omit the column entirely. Supply onSave instead of formAction to drive it from a client handler.

Two details worth knowing:

  • The tenant column's Default option never names the code default, because the tenant scope inherits — from the global override, and, when a FeatureTenantHierarchyProvider is configured, from ancestor tenants too. It names the inherited state when the row carries inheritedEnabled (the helper sets it whenever it is exactly knowable, i.e. when the tenant has no override of its own) and otherwise reads "Default (inherited)". The global column's Default does name the code default, because the global scope inherits nothing.
  • Unsaved edits are discarded whenever contextKey changes, or, when you omit it, whenever features is replaced with a new array. Pass the tenant id as contextKey so a half-made choice for one tenant can never be submitted against another's rows.

5. Wire the write with your own permission check. setFeatureOverride() refuses any key without a definition and any scope the resolver would never read back — an unknown scopeType, a global write under anything but GLOBAL_FEATURE_SCOPE_ID, or a blank/untrimmed tenant id — then delegates to FeatureOverrideService, which asks your authorizer and fails closed:

export const actions = {
  saveFeature: async (event) => {
    const auth = requirePermission(event, APP_PERMISSIONS.tenantAdmin);
    const form = await event.request.formData();
    const settings = await FeatureSettingsService.create(dbOptions, {
      // Your decision, bound to this caller. Returning anything but `true` denies.
      authorize: (request) =>
        request.scopeType === 'tenant' && request.scopeId === auth.tenantId,
    });

    try {
      await settings.setTenantFeatureOverride(
        String(form.get('featureKey') ?? ''),
        auth.tenantId,
        featureOverrideEffectFromValue(form.get('tenantEffect')),
      );
    } catch (error) {
      if (error instanceof UnknownFeatureKeyError) return fail(400, { error: 'Unknown feature.' });
      if (error instanceof InvalidFeatureScopeError) return fail(400, { error: 'Invalid scope.' });
      if (error instanceof FeatureOverrideAuthorizationError) return fail(403, { error: 'Not permitted.' });
      throw error;
    }
    return { message: 'Feature overrides saved.' };
  },
};

Constructing the service without an authorize option makes it read-only: every write then fails closed with FeatureOverrideAuthorizationError. That is the right shape for a load function.

What the consumer still owns

  • the route, its navigation entry, and the page shell;
  • the permission check on both the load and the action;
  • the authorize callback (this package never decides who may write);
  • resolving the session's tenantId — a tenant id from the URL or a form field is a selector, not authorization;
  • calling FeatureSyncService at startup.

Feature keys are persisted identifiers

Overrides are stored keyed by the exact featureKey string and resolved by that string at runtime. Renaming a key orphans every existing override, silently reverting all tenants to the definition default — the change looks harmless in a diff and shows up as flags mysteriously resetting. Treat a key as immutable once shipped. A rename needs a data migration that rewrites _smrt_feature_overrides.feature_key, not an edit. (Renaming the owning package is the usual way this happens: migrate stored keys when the qualified class identity changes.)

Documentation

版本与发布记录

@happyvertical/smrt-features 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-features 的常见问题

@happyvertical/smrt-features 是什么?

Code-first feature flags and tenant-aware overrides for the SMRT framework

如何安装 @happyvertical/smrt-features?

在项目目录运行 npm install @happyvertical/smrt-features,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-features 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-features 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-features 可以商用吗?

@happyvertical/smrt-features 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-features 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-features 在 2026/10/17 – 2026/11/15 这 30 天内被下载 20,640 次,日均约 688 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-features 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。