@syncular/core 0.0.1-123 → 0.0.1-124

package/dist/scopes/index.d.ts

@@ -9,6 +9,10 @@
  * Scope pattern string, e.g., 'user:{user_id}', 'project:{project_id}'
  */
 export type ScopePattern = string;
+/**
+ * Scope value for a single scope key.
+ */
+export type ScopeValue = string | string[];
 /**
  * Scope values - the actual values for scope variables.
  * Values can be single strings or arrays (for multi-value subscriptions).
@@ -18,7 +22,7 @@ export type ScopePattern = string;
  * { project_id: ['P1', 'P2'] }
  * { year: '2025', month: '03' }
  */
-export type ScopeValues = Record<string, string | string[]>;
+export type ScopeValues = Record<string, ScopeValue>;
 /**
  * Stored scopes on a change - always single values (not arrays).
  * This is what gets stored in the JSONB column.
@@ -27,6 +31,38 @@ export type ScopeValues = Record<string, string | string[]>;
  * { user_id: 'U1', project_id: 'P1' }
  */
 export type StoredScopes = Record<string, string>;
+/**
+ * Extract scope keys from a scope pattern at the type level.
+ *
+ * @example
+ * ScopeKeysFromPattern<'user:{user_id}'> // 'user_id'
+ * ScopeKeysFromPattern<'event:{year}:{month}'> // 'year' | 'month'
+ */
+export type ScopeKeysFromPattern<Pattern extends ScopePattern> = string extends Pattern ? string : Pattern extends `${string}{${infer Key}}${infer Rest}` ? Key | ScopeKeysFromPattern<Rest> : never;
+/**
+ * Resolve the pattern string from a scope definition.
+ */
+export type ScopePatternFromDefinition<Definition extends ScopeDefinition> = Definition extends ScopePattern ? Definition : Definition extends {
+    pattern: infer Pattern extends ScopePattern;
+} ? Pattern : never;
+/**
+ * Extract scope keys from a list of scope definitions.
+ */
+export type ScopeKeysFromDefinitions<Definitions extends readonly ScopeDefinition[]> = ScopeKeysFromPattern<ScopePatternFromDefinition<Definitions[number]>>;
+/**
+ * Scope values constrained to known scope keys.
+ *
+ * Unknown keys are rejected at compile-time when literals are used.
+ */
+export type ScopeValuesForKeys<ScopeKeys extends string> = Partial<Record<ScopeKeys, ScopeValue>>;
+/**
+ * Scope values inferred from scope definitions.
+ */
+export type ScopeValuesFromPatterns<Definitions extends readonly ScopeDefinition[]> = ScopeValuesForKeys<ScopeKeysFromDefinitions<Definitions>>;
+/**
+ * Stored scopes constrained to known scope keys.
+ */
+export type StoredScopesForKeys<ScopeKeys extends string> = Partial<Record<ScopeKeys, string>>;
 /**
  * Simplified scope definition.
  * Can be a simple pattern string or an object with explicit column mapping.
@@ -42,10 +78,17 @@ export type StoredScopes = Record<string, string>;
  * ]
  * ```
  */
-export type ScopeDefinition = string | {
-    pattern: string;
+export type ScopeDefinition = ScopePattern | {
+    pattern: ScopePattern;
     column: string;
 };
+/**
+ * Keep scope definitions as a typed tuple for downstream inference.
+ *
+ * @example
+ * const scopes = defineScopePatterns(['user:{user_id}'] as const);
+ */
+export declare function defineScopePatterns<const Definitions extends readonly ScopeDefinition[]>(scopes: Definitions): Definitions;
 /**
  * Normalize scope definitions to a pattern-to-column map.
  *
@@ -53,7 +96,7 @@ export type ScopeDefinition = string | {
  * normalizeScopes(['user:{user_id}'])
  * // → { 'user:{user_id}': 'user_id' }
  */
-export declare function normalizeScopes(scopes: ScopeDefinition[]): Record<string, string>;
+export declare function normalizeScopes(scopes: readonly ScopeDefinition[]): Record<ScopePattern, string>;
 /**
  * Extract variable names from a scope pattern.
  *

package/dist/scopes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA+B3E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EAAE,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAIhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,CAAC,OAAO,SAAS,YAAY,IAC3D,MAAM,SAAS,OAAO,GAClB,MAAM,GACN,OAAO,SAAS,GAAG,MAAM,IAAI,MAAM,GAAG,IAAI,MAAM,IAAI,EAAE,GACpD,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,GAChC,KAAK,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,0BAA0B,CAAC,UAAU,SAAS,eAAe,IACvE,UAAU,SAAS,YAAY,GAC3B,UAAU,GACV,UAAU,SAAS;IAAE,OAAO,EAAE,MAAM,OAAO,SAAS,YAAY,CAAA;CAAE,GAChE,OAAO,GACP,KAAK,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAClC,WAAW,SAAS,SAAS,eAAe,EAAE,IAC5C,oBAAoB,CAAC,0BAA0B,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,SAAS,SAAS,MAAM,IAAI,OAAO,CAChE,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,CACjC,WAAW,SAAS,SAAS,eAAe,EAAE,IAC5C,kBAAkB,CAAC,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,SAAS,SAAS,MAAM,IAAI,OAAO,CACjE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAC1B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ;IAAE,OAAO,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,CAAC,WAAW,SAAS,SAAS,eAAe,EAAE,EACpD,MAAM,EAAE,WAAW,GAAG,WAAW,CAElC;AA+BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAgB9B;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAIhE"}

package/dist/scopes/index.js

@@ -5,6 +5,15 @@
  * Scopes are stored as JSONB on changes for flexible filtering.
  * Patterns use `{placeholder}` syntax to extract or inject values.
  */
+/**
+ * Keep scope definitions as a typed tuple for downstream inference.
+ *
+ * @example
+ * const scopes = defineScopePatterns(['user:{user_id}'] as const);
+ */
+export function defineScopePatterns(scopes) {
+    return scopes;
+}
 // ── Pattern parsing (internal helpers) ───────────────────────────────
 /**
  * Extract the placeholder name from a pattern.

package/dist/scopes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8CH,0IAAwE;AAExE;;;GAGG;AACH,SAAS,kBAAkB,CAAC,OAAe,EAIlC;IACP,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE;QACjB,WAAW,EAAE,KAAK,CAAC,CAAC,CAAE;QACtB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE;KAClB,CAAC;AAAA,CACH;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,OAAe,EAAiB;IAC1D,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC;AAAA,CACpC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAyB,EACD;IACxB,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAC9C,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,iDAAiD,CACzE,CAAC;YACJ,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACf;AAED,4JAAwE;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB,EAAY;IAChE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAAA,CAC3C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scopes/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2GH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAEjC,MAAmB,EAAe;IAClC,OAAO,MAAM,CAAC;AAAA,CACf;AAED,0IAAwE;AAExE;;;GAGG;AACH,SAAS,kBAAkB,CAAC,OAAe,EAIlC;IACP,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE;QACjB,WAAW,EAAE,KAAK,CAAC,CAAC,CAAE;QACtB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE;KAClB,CAAC;AAAA,CACH;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,OAAe,EAAiB;IAC1D,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC;AAAA,CACpC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAkC,EACJ;IAC9B,MAAM,MAAM,GAAiC,EAAE,CAAC;IAChD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAC9C,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,iDAAiD,CACzE,CAAC;YACJ,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACf;AAED,4JAAwE;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB,EAAY;IAChE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAAA,CAC3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.0.1-123",
+  "version": "0.0.1-124",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "MIT",
   "author": "Benjamin Kniffler",

package/src/scopes/index.ts

@@ -13,6 +13,11 @@
  */
 export type ScopePattern = string;
 
+/**
+ * Scope value for a single scope key.
+ */
+export type ScopeValue = string | string[];
+
 /**
  * Scope values - the actual values for scope variables.
  * Values can be single strings or arrays (for multi-value subscriptions).
@@ -22,7 +27,7 @@ export type ScopePattern = string;
  * { project_id: ['P1', 'P2'] }
  * { year: '2025', month: '03' }
  */
-export type ScopeValues = Record<string, string | string[]>;
+export type ScopeValues = Record<string, ScopeValue>;
 
 /**
  * Stored scopes on a change - always single values (not arrays).
@@ -33,6 +38,60 @@ export type ScopeValues = Record<string, string | string[]>;
  */
 export type StoredScopes = Record<string, string>;
 
+/**
+ * Extract scope keys from a scope pattern at the type level.
+ *
+ * @example
+ * ScopeKeysFromPattern<'user:{user_id}'> // 'user_id'
+ * ScopeKeysFromPattern<'event:{year}:{month}'> // 'year' | 'month'
+ */
+export type ScopeKeysFromPattern<Pattern extends ScopePattern> =
+  string extends Pattern
+    ? string
+    : Pattern extends `${string}{${infer Key}}${infer Rest}`
+      ? Key | ScopeKeysFromPattern<Rest>
+      : never;
+
+/**
+ * Resolve the pattern string from a scope definition.
+ */
+export type ScopePatternFromDefinition<Definition extends ScopeDefinition> =
+  Definition extends ScopePattern
+    ? Definition
+    : Definition extends { pattern: infer Pattern extends ScopePattern }
+      ? Pattern
+      : never;
+
+/**
+ * Extract scope keys from a list of scope definitions.
+ */
+export type ScopeKeysFromDefinitions<
+  Definitions extends readonly ScopeDefinition[],
+> = ScopeKeysFromPattern<ScopePatternFromDefinition<Definitions[number]>>;
+
+/**
+ * Scope values constrained to known scope keys.
+ *
+ * Unknown keys are rejected at compile-time when literals are used.
+ */
+export type ScopeValuesForKeys<ScopeKeys extends string> = Partial<
+  Record<ScopeKeys, ScopeValue>
+>;
+
+/**
+ * Scope values inferred from scope definitions.
+ */
+export type ScopeValuesFromPatterns<
+  Definitions extends readonly ScopeDefinition[],
+> = ScopeValuesForKeys<ScopeKeysFromDefinitions<Definitions>>;
+
+/**
+ * Stored scopes constrained to known scope keys.
+ */
+export type StoredScopesForKeys<ScopeKeys extends string> = Partial<
+  Record<ScopeKeys, string>
+>;
+
 /**
  * Simplified scope definition.
  * Can be a simple pattern string or an object with explicit column mapping.
@@ -48,7 +107,21 @@ export type StoredScopes = Record<string, string>;
  * ]
  * ```
  */
-export type ScopeDefinition = string | { pattern: string; column: string };
+export type ScopeDefinition =
+  | ScopePattern
+  | { pattern: ScopePattern; column: string };
+
+/**
+ * Keep scope definitions as a typed tuple for downstream inference.
+ *
+ * @example
+ * const scopes = defineScopePatterns(['user:{user_id}'] as const);
+ */
+export function defineScopePatterns<
+  const Definitions extends readonly ScopeDefinition[],
+>(scopes: Definitions): Definitions {
+  return scopes;
+}
 
 // ── Pattern parsing (internal helpers) ───────────────────────────────
 
@@ -87,9 +160,9 @@ function getPlaceholderName(pattern: string): string | null {
  * // → { 'user:{user_id}': 'user_id' }
  */
 export function normalizeScopes(
-  scopes: ScopeDefinition[]
-): Record<string, string> {
-  const result: Record<string, string> = {};
+  scopes: readonly ScopeDefinition[]
+): Record<ScopePattern, string> {
+  const result: Record<ScopePattern, string> = {};
   for (const scope of scopes) {
     if (typeof scope === 'string') {
       const placeholder = getPlaceholderName(scope);