@traffical/core 0.1.2

package/src/ids/index.ts

@@ -0,0 +1,221 @@
+/**
+ * ID Generation Utilities
+ *
+ * Provides consistent ID generation with type prefixes for all entities and events.
+ *
+ * Entity IDs: 8-character NanoID with prefix (e.g., "proj_hVF1cCoC")
+ * - Compact and URL-friendly
+ * - 64^8 = 281 trillion combinations
+ * - With DB constraints, collisions are handled via retry
+ *
+ * Event IDs: ULID with prefix (e.g., "dec_01JHFK1WWMMG7M0XPEBTYXZEBW")
+ * - Lexicographically sortable (time-ordered)
+ * - Contains millisecond timestamp for analytics
+ */
+
+import { customAlphabet } from "nanoid";
+import { ulid } from "ulid";
+
+// =============================================================================
+// NanoID Configuration
+// =============================================================================
+
+/**
+ * URL-safe alphabet for NanoID (64 characters).
+ * Includes: 0-9, A-Z, a-z (no special chars to avoid URL encoding issues)
+ */
+const NANOID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+/**
+ * Default length for entity IDs (without prefix).
+ * 64^8 = 281,474,976,710,656 (~281 trillion) combinations.
+ */
+const ENTITY_ID_LENGTH = 8;
+
+/**
+ * NanoID generator with custom alphabet.
+ */
+const nanoid = customAlphabet(NANOID_ALPHABET, ENTITY_ID_LENGTH);
+
+// =============================================================================
+// ID Prefixes
+// =============================================================================
+
+/**
+ * Entity ID prefixes for each entity type.
+ */
+export type EntityIdPrefix =
+  | "org"     // Organization
+  | "proj"    // Project
+  | "env"     // Environment
+  | "ns"      // Namespace
+  | "lay"     // Layer
+  | "pol"     // Policy
+  | "alloc"   // Allocation
+  | "param"   // Parameter
+  | "dom"     // DOM Binding
+  | "ovr"     // Environment Override
+  | "ak";     // API Key
+
+/**
+ * Event ID prefixes for each event type.
+ */
+export type EventIdPrefix = "dec" | "exp" | "trk";
+
+// =============================================================================
+// Generic ID Generation
+// =============================================================================
+
+/**
+ * Generates a prefixed 8-char NanoID for the specified entity type.
+ *
+ * @param prefix - The entity type prefix
+ * @returns A prefixed NanoID string (e.g., "proj_hVF1cCoC")
+ */
+export function generateEntityId(prefix: EntityIdPrefix): string {
+  return `${prefix}_${nanoid()}`;
+}
+
+/**
+ * Generates a prefixed ULID for the specified event type.
+ * Events use ULID for time-sortability in analytics.
+ *
+ * @param prefix - The event type prefix
+ * @returns A prefixed ULID string (e.g., "dec_01JHFK1WWMMG7M0XPEBTYXZEBW")
+ */
+export function generateEventId(prefix: EventIdPrefix): string {
+  return `${prefix}_${ulid()}`;
+}
+
+/**
+ * Generates a plain 8-char NanoID without prefix.
+ * Used for internal IDs that don't need type identification.
+ */
+export function generateShortId(): string {
+  return nanoid();
+}
+
+// =============================================================================
+// Entity ID Convenience Functions
+// =============================================================================
+
+/** Generates an Organization ID with "org_" prefix */
+export function generateOrgId(): string {
+  return generateEntityId("org");
+}
+
+/** Generates a Project ID with "proj_" prefix */
+export function generateProjectId(): string {
+  return generateEntityId("proj");
+}
+
+/** Generates an Environment ID with "env_" prefix */
+export function generateEnvironmentId(): string {
+  return generateEntityId("env");
+}
+
+/** Generates a Namespace ID with "ns_" prefix */
+export function generateNamespaceId(): string {
+  return generateEntityId("ns");
+}
+
+/** Generates a Layer ID with "lay_" prefix */
+export function generateLayerId(): string {
+  return generateEntityId("lay");
+}
+
+/** Generates a Policy ID with "pol_" prefix */
+export function generatePolicyId(): string {
+  return generateEntityId("pol");
+}
+
+/** Generates an Allocation ID with "alloc_" prefix */
+export function generateAllocationId(): string {
+  return generateEntityId("alloc");
+}
+
+/** Generates a Parameter ID with "param_" prefix */
+export function generateParameterId(): string {
+  return generateEntityId("param");
+}
+
+/** Generates a DOM Binding ID with "dom_" prefix */
+export function generateDomBindingId(): string {
+  return generateEntityId("dom");
+}
+
+/** Generates an Environment Override ID with "ovr_" prefix */
+export function generateOverrideId(): string {
+  return generateEntityId("ovr");
+}
+
+/** Generates an API Key ID with "ak_" prefix */
+export function generateApiKeyId(): string {
+  return generateEntityId("ak");
+}
+
+// =============================================================================
+// Event ID Convenience Functions (Keep ULID for time-sortability)
+// =============================================================================
+
+/** Generates a Decision event ID with "dec_" prefix (ULID) */
+export function generateDecisionId(): string {
+  return generateEventId("dec");
+}
+
+/** Generates an Exposure event ID with "exp_" prefix (ULID) */
+export function generateExposureId(): string {
+  return generateEventId("exp");
+}
+
+/** Generates a Track event ID with "trk_" prefix (ULID) */
+export function generateTrackEventId(): string {
+  return generateEventId("trk");
+}
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+/**
+ * Extracts the timestamp from a ULID-based ID.
+ * Only works for event IDs (ULID format).
+ *
+ * @param id - A prefixed ULID (e.g., "dec_01JHFK1WWMMG7M0XPEBTYXZEBW")
+ * @returns The timestamp as a Date, or null if invalid
+ */
+export function getIdTimestamp(id: string): Date | null {
+  // Extract the ULID part (after the prefix and underscore)
+  const parts = id.split("_");
+  if (parts.length < 2) {
+    return null;
+  }
+
+  const ulidPart = parts[1];
+  if (!ulidPart || ulidPart.length !== 26) {
+    return null;
+  }
+
+  // ULID timestamp is encoded in the first 10 characters (Crockford's Base32)
+  const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+  const TIME_LEN = 10;
+
+  let time = 0;
+  for (let i = 0; i < TIME_LEN; i++) {
+    const char = ulidPart.charAt(i).toUpperCase();
+    const index = ENCODING.indexOf(char);
+    if (index === -1) {
+      return null;
+    }
+    time = time * 32 + index;
+  }
+
+  return new Date(time);
+}
+
+/**
+ * @deprecated Use getIdTimestamp instead
+ */
+export function getEventIdTimestamp(eventId: string): Date | null {
+  return getIdTimestamp(eventId);
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+/**
+ * @traffical/core
+ *
+ * Pure TypeScript core for Traffical SDK.
+ * This package performs no I/O and can be used in any JavaScript environment.
+ *
+ * Key features:
+ * - Deterministic parameter resolution
+ * - FNV-1a hashing for bucket assignment
+ * - Condition evaluation for targeting
+ * - Defaults-based graceful degradation
+ */
+
+// Types
+export type {
+  // Base types
+  Timestamp,
+  Id,
+  ParameterType,
+  ParameterValue,
+  Context,
+  // Bundle types
+  ConfigBundle,
+  BundleHashingConfig,
+  BundleParameter,
+  BundleDOMBinding,
+  BundleLayer,
+  BundlePolicy,
+  BundleAllocation,
+  BundleCondition,
+  PolicyState,
+  PolicyKind,
+  ConditionOperator,
+  // Per-entity types
+  EntityConfig,
+  EntityWeights,
+  BundleEntityPolicyState,
+  // SDK types
+  ParameterDefaults,
+  DecisionResult,
+  DecisionMetadata,
+  LayerResolution,
+  // Event types
+  BaseEventFields,
+  ExposureEvent,
+  TrackEvent,
+  TrackAttribution,
+  DecisionEvent,
+  TrackableEvent,
+  // Client types
+  TrafficalClientOptions,
+  GetParamsOptions,
+  DecideOptions,
+  TrackOptions,
+} from "./types/index.js";
+
+// Hashing
+export {
+  fnv1a,
+  computeBucket,
+  isInBucketRange,
+  findMatchingAllocation,
+  percentageToBucketRange,
+  createBucketRanges,
+} from "./hashing/index.js";
+
+// Resolution
+export {
+  resolveParameters,
+  decide,
+  getUnitKeyValue,
+  evaluateCondition,
+  evaluateConditions,
+  // Condition builders
+  eq,
+  neq,
+  inValues,
+  notIn,
+  gt,
+  gte,
+  lt,
+  lte,
+  contains,
+  startsWith,
+  endsWith,
+  regex,
+  exists,
+  notExists,
+} from "./resolution/index.js";
+
+// Deduplication
+export {
+  DecisionDeduplicator,
+  type DecisionDeduplicatorOptions,
+} from "./dedup/index.js";
+
+// ID Generation
+export {
+  // Event IDs (ULID - time-sortable)
+  generateEventId,
+  generateDecisionId,
+  generateExposureId,
+  generateTrackEventId,
+  // Entity IDs (8-char NanoID)
+  generateEntityId,
+  generateShortId,
+  generateOrgId,
+  generateProjectId,
+  generateEnvironmentId,
+  generateNamespaceId,
+  generateLayerId,
+  generatePolicyId,
+  generateAllocationId,
+  generateParameterId,
+  generateDomBindingId,
+  generateOverrideId,
+  generateApiKeyId,
+  // Utilities
+  getIdTimestamp,
+  getEventIdTimestamp, // deprecated
+  // Types
+  type EventIdPrefix,
+  type EntityIdPrefix,
+} from "./ids/index.js";
+
+// Edge Client (for per-entity policies)
+export {
+  EdgeClient,
+  createEdgeDecideRequest,
+  type EdgeClientConfig,
+  type EdgeDecideRequest,
+  type EdgeDecideResponse,
+  type EdgeBatchDecideRequest,
+  type EdgeBatchDecideResponse,
+} from "./edge/index.js";
+

package/src/resolution/conditions.ts

@@ -0,0 +1,253 @@
+/**
+ * Condition Evaluation
+ *
+ * Evaluates context predicates to determine policy eligibility.
+ * Conditions are AND-ed together: all must match for a policy to apply.
+ */
+
+import type { Context, BundleCondition } from "../types/index.js";
+
+/**
+ * Evaluates a single condition against a context.
+ *
+ * @param condition - The condition to evaluate
+ * @param context - The context to evaluate against
+ * @returns True if the condition matches
+ */
+export function evaluateCondition(
+  condition: BundleCondition,
+  context: Context
+): boolean {
+  const { field, op, value, values } = condition;
+
+  // Get the context value using dot notation
+  const contextValue = getNestedValue(context, field);
+
+  switch (op) {
+    case "eq":
+      return contextValue === value;
+
+    case "neq":
+      return contextValue !== value;
+
+    case "in":
+      if (!Array.isArray(values)) return false;
+      return values.includes(contextValue);
+
+    case "nin":
+      if (!Array.isArray(values)) return true;
+      return !values.includes(contextValue);
+
+    case "gt":
+      return (
+        typeof contextValue === "number" && contextValue > (value as number)
+      );
+
+    case "gte":
+      return (
+        typeof contextValue === "number" && contextValue >= (value as number)
+      );
+
+    case "lt":
+      return (
+        typeof contextValue === "number" && contextValue < (value as number)
+      );
+
+    case "lte":
+      return (
+        typeof contextValue === "number" && contextValue <= (value as number)
+      );
+
+    case "contains":
+      return (
+        typeof contextValue === "string" &&
+        typeof value === "string" &&
+        contextValue.includes(value)
+      );
+
+    case "startsWith":
+      return (
+        typeof contextValue === "string" &&
+        typeof value === "string" &&
+        contextValue.startsWith(value)
+      );
+
+    case "endsWith":
+      return (
+        typeof contextValue === "string" &&
+        typeof value === "string" &&
+        contextValue.endsWith(value)
+      );
+
+    case "regex":
+      if (typeof contextValue !== "string" || typeof value !== "string") {
+        return false;
+      }
+      try {
+        const regex = new RegExp(value);
+        return regex.test(contextValue);
+      } catch {
+        return false;
+      }
+
+    case "exists":
+      return contextValue !== undefined && contextValue !== null;
+
+    case "notExists":
+      return contextValue === undefined || contextValue === null;
+
+    default:
+      // Unknown operator, fail safe by not matching
+      return false;
+  }
+}
+
+/**
+ * Evaluates all conditions against a context.
+ * All conditions must match (AND logic).
+ *
+ * @param conditions - Array of conditions
+ * @param context - The context to evaluate against
+ * @returns True if all conditions match (or if there are no conditions)
+ */
+export function evaluateConditions(
+  conditions: BundleCondition[],
+  context: Context
+): boolean {
+  // Empty conditions = always match
+  if (conditions.length === 0) {
+    return true;
+  }
+
+  // All conditions must match (AND)
+  return conditions.every((condition) => evaluateCondition(condition, context));
+}
+
+/**
+ * Gets a nested value from an object using dot notation.
+ *
+ * @example
+ * getNestedValue({ user: { name: "Alice" } }, "user.name") // "Alice"
+ * getNestedValue({ tags: ["a", "b"] }, "tags.0") // "a"
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split(".");
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+
+    if (typeof current === "object") {
+      current = (current as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+
+  return current;
+}
+
+// =============================================================================
+// Condition Builder Helpers
+// =============================================================================
+
+/**
+ * Creates an equality condition.
+ */
+export function eq(field: string, value: unknown): BundleCondition {
+  return { field, op: "eq", value };
+}
+
+/**
+ * Creates a not-equal condition.
+ */
+export function neq(field: string, value: unknown): BundleCondition {
+  return { field, op: "neq", value };
+}
+
+/**
+ * Creates an "in" condition.
+ */
+export function inValues(field: string, values: unknown[]): BundleCondition {
+  return { field, op: "in", values };
+}
+
+/**
+ * Creates a "not in" condition.
+ */
+export function notIn(field: string, values: unknown[]): BundleCondition {
+  return { field, op: "nin", values };
+}
+
+/**
+ * Creates a greater-than condition.
+ */
+export function gt(field: string, value: number): BundleCondition {
+  return { field, op: "gt", value };
+}
+
+/**
+ * Creates a greater-than-or-equal condition.
+ */
+export function gte(field: string, value: number): BundleCondition {
+  return { field, op: "gte", value };
+}
+
+/**
+ * Creates a less-than condition.
+ */
+export function lt(field: string, value: number): BundleCondition {
+  return { field, op: "lt", value };
+}
+
+/**
+ * Creates a less-than-or-equal condition.
+ */
+export function lte(field: string, value: number): BundleCondition {
+  return { field, op: "lte", value };
+}
+
+/**
+ * Creates a string contains condition.
+ */
+export function contains(field: string, value: string): BundleCondition {
+  return { field, op: "contains", value };
+}
+
+/**
+ * Creates a string starts-with condition.
+ */
+export function startsWith(field: string, value: string): BundleCondition {
+  return { field, op: "startsWith", value };
+}
+
+/**
+ * Creates a string ends-with condition.
+ */
+export function endsWith(field: string, value: string): BundleCondition {
+  return { field, op: "endsWith", value };
+}
+
+/**
+ * Creates a regex match condition.
+ */
+export function regex(field: string, pattern: string): BundleCondition {
+  return { field, op: "regex", value: pattern };
+}
+
+/**
+ * Creates an exists condition.
+ */
+export function exists(field: string): BundleCondition {
+  return { field, op: "exists" };
+}
+
+/**
+ * Creates a not-exists condition.
+ */
+export function notExists(field: string): BundleCondition {
+  return { field, op: "notExists" };
+}
+