@flaghoist/core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,45 @@
+# @flaghoist/core
+
+The evaluation engine behind Flaghoist. Flag schema, targeting rules, percentage rollouts, and the
+storage and auth interfaces the rest of the packages build on.
+
+Zero dependencies, and no knowledge of HTTP or of where flags are stored.
+
+You usually get this as a dependency of `@flaghoist/server` rather than installing it yourself.
+Install it directly if you are writing a storage adapter, or if you want to evaluate flags in
+process without running a server.
+
+```bash
+npm install @flaghoist/core
+```
+
+```ts
+import { evaluate, createFlag } from '@flaghoist/core'
+
+const flag = createFlag('new-checkout', {
+  enabled: true,
+  rollout: { percentage: 25 },
+})
+
+const result = evaluate(flag.flag, { targetingKey: 'user-123', plan: 'pro' })
+// { value: true, reason: 'SPLIT', ... }
+```
+
+## How evaluation works
+
+Rules are ordered and the first match wins, with conditions inside a rule combined with AND. If no
+rule matches, the percentage rollout decides.
+
+Rollouts bucket users with SHA-256 over the targeting key, so the same user always lands in the same
+place. Going from 10 percent to 20 percent adds people without reshuffling the ones already in.
+
+Flags are boolean. There are no multivariate values, and evaluation returns a reason so you can tell
+why you got what you got.
+
+## Status
+
+Pre-alpha, built and maintained by one person. The API can still change without notice, and
+production use is not recommended yet. If you try it and something breaks, an issue is genuinely
+useful.
+
+Apache-2.0. Part of [Flaghoist](https://github.com/flaghoist/flaghoist).

package/dist/index.cjs

@@ -33,8 +33,7 @@ __export(index_exports, {
   matchCondition: () => matchCondition,
   matchesAllConditions: () => matchesAllConditions,
   parseFlag: () => parseFlag,
-  stickyBucket: () => stickyBucket,
-  version: () => version
+  stickyBucket: () => stickyBucket
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -62,7 +61,8 @@ var LIMITS = {
   maxRules: 100,
   maxConditionsPerRule: 50,
   maxListItems: 1e3,
-  maxValueLength: 1024
+  maxValueLength: 1024,
+  maxDescriptionLength: 2048
 };
 var FLAG_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 var FORBIDDEN_ATTRIBUTES = /* @__PURE__ */ new Set([
@@ -250,6 +250,9 @@ function parseFlag(input) {
   if (typeof o.enabled !== "boolean") return null;
   const rollout = asRecord(o.rollout);
   const percentage = rollout && typeof rollout.percentage === "number" ? clampPercentage(rollout.percentage) : 0;
+  if (typeof o.description === "string" && o.description.length > LIMITS.maxDescriptionLength) {
+    return null;
+  }
   const rawRules = Array.isArray(o.rules) ? o.rules : [];
   if (rawRules.length > LIMITS.maxRules) return null;
   const rules = rawRules.map(parseRule).filter((r) => r !== null);
@@ -277,9 +280,6 @@ function createFlag(input) {
     metadata: { createdBy: identity, createdAt: now, updatedBy: identity, updatedAt: now }
   };
 }
-
-// src/index.ts
-var version = "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FLAG_KEY_RULE,
@@ -295,6 +295,5 @@ var version = "0.0.0";
   matchCondition,
   matchesAllConditions,
   parseFlag,
-  stickyBucket,
-  version
+  stickyBucket
 });

package/dist/index.d.cts

@@ -117,6 +117,7 @@ declare const LIMITS: {
     readonly maxConditionsPerRule: 50;
     readonly maxListItems: 1000;
     readonly maxValueLength: 1024;
+    readonly maxDescriptionLength: 2048;
 };
 /**
  * Attribute names that resolve onto the prototype chain rather than to real data. They are
@@ -185,6 +186,4 @@ interface CreateFlagInput {
  */
 declare function createFlag(input: CreateFlagInput): FeatureFlag;
 
-declare const version = "0.0.0";
-
-export { type AttributeValue, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagMetadata, LIMITS, type Operator, type RuleResult, type StorageAdapter, type TargetingRule, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidFlagKey, matchCondition, matchesAllConditions, parseFlag, stickyBucket, version };
+export { type AttributeValue, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagMetadata, LIMITS, type Operator, type RuleResult, type StorageAdapter, type TargetingRule, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidFlagKey, matchCondition, matchesAllConditions, parseFlag, stickyBucket };

package/dist/index.d.ts

@@ -117,6 +117,7 @@ declare const LIMITS: {
     readonly maxConditionsPerRule: 50;
     readonly maxListItems: 1000;
     readonly maxValueLength: 1024;
+    readonly maxDescriptionLength: 2048;
 };
 /**
  * Attribute names that resolve onto the prototype chain rather than to real data. They are
@@ -185,6 +186,4 @@ interface CreateFlagInput {
  */
 declare function createFlag(input: CreateFlagInput): FeatureFlag;
 
-declare const version = "0.0.0";
-
-export { type AttributeValue, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagMetadata, LIMITS, type Operator, type RuleResult, type StorageAdapter, type TargetingRule, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidFlagKey, matchCondition, matchesAllConditions, parseFlag, stickyBucket, version };
+export { type AttributeValue, type AuthContext, type AuthVerifier, type Condition, type ConditionValue, type CreateFlagInput, type EvaluationContext, type EvaluationReason, type EvaluationResult, FLAG_KEY_RULE, FORBIDDEN_ATTRIBUTES, type FeatureFlag, type FlagMetadata, LIMITS, type Operator, type RuleResult, type StorageAdapter, type TargetingRule, clampPercentage, compareSemver, createFlag, evaluate, evaluateAll, isInRollout, isValidFlagKey, matchCondition, matchesAllConditions, parseFlag, stickyBucket };

package/dist/index.js

@@ -22,7 +22,8 @@ var LIMITS = {
   maxRules: 100,
   maxConditionsPerRule: 50,
   maxListItems: 1e3,
-  maxValueLength: 1024
+  maxValueLength: 1024,
+  maxDescriptionLength: 2048
 };
 var FLAG_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 var FORBIDDEN_ATTRIBUTES = /* @__PURE__ */ new Set([
@@ -210,6 +211,9 @@ function parseFlag(input) {
   if (typeof o.enabled !== "boolean") return null;
   const rollout = asRecord(o.rollout);
   const percentage = rollout && typeof rollout.percentage === "number" ? clampPercentage(rollout.percentage) : 0;
+  if (typeof o.description === "string" && o.description.length > LIMITS.maxDescriptionLength) {
+    return null;
+  }
   const rawRules = Array.isArray(o.rules) ? o.rules : [];
   if (rawRules.length > LIMITS.maxRules) return null;
   const rules = rawRules.map(parseRule).filter((r) => r !== null);
@@ -237,9 +241,6 @@ function createFlag(input) {
     metadata: { createdBy: identity, createdAt: now, updatedBy: identity, updatedAt: now }
   };
 }
-
-// src/index.ts
-var version = "0.0.0";
 export {
   FLAG_KEY_RULE,
   FORBIDDEN_ATTRIBUTES,
@@ -254,6 +255,5 @@ export {
   matchCondition,
   matchesAllConditions,
   parseFlag,
-  stickyBucket,
-  version
+  stickyBucket
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaghoist/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Flag schema, evaluation engine, and storage/auth interfaces for Flaghoist. Zero dependencies.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,6 +29,22 @@
   "publishConfig": {
     "access": "public"
   },
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "evaluation",
+    "targeting",
+    "percentage-rollout"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flaghoist/flaghoist.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/flaghoist/flaghoist#readme",
+  "bugs": {
+    "url": "https://github.com/flaghoist/flaghoist/issues"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "test": "vitest run --passWithNoTests",