@almadar/core 2.0.0 → 2.1.1

package/dist/types/index.d.ts

@@ -433,6 +433,148 @@ interface ValidationDocument {
     validatedAt: number;
 }
 
+/**
+ * Service Contract Types
+ *
+ * Formalizes the two public surfaces of an Almadar service:
+ * 1. Call-Service Contract — what the .orb schema can invoke on the TypeScript package
+ * 2. Event Contract — what events enter/leave the service
+ *
+ * Plus internal-but-standardized patterns:
+ * 3. StoreContract — database abstraction boundary
+ * 4. LazyService — singleton lifecycle pattern
+ *
+ * @packageDocumentation
+ */
+/**
+ * Action definition for a service contract.
+ * Each action has typed params and a typed result.
+ */
+interface ServiceAction {
+    params: Record<string, unknown>;
+    result: unknown;
+}
+/**
+ * What `["call-service", "name", "action", {...}]` actually calls at runtime.
+ * Each service defines its action map as a Record<string, ServiceAction>.
+ *
+ * @example
+ * ```typescript
+ * type LLMActions = {
+ *   generate: {
+ *     params: { userPrompt: string; model: string; maxTokens: number };
+ *     result: { content: string; tokensUsed: number; latencyMs: number };
+ *   };
+ * };
+ *
+ * class LLMService implements ServiceContract<LLMActions> {
+ *   async execute(action, params) { ... }
+ * }
+ * ```
+ */
+interface ServiceContract<Actions extends Record<string, ServiceAction>> {
+    execute<A extends keyof Actions & string>(action: A, params: Actions[A]["params"]): Promise<Actions[A]["result"]>;
+}
+/**
+ * Event contract — what events the service emits/listens with typed payloads.
+ * Derived from the `.orb` schema's `emits` and `listens` declarations.
+ *
+ * @example
+ * ```typescript
+ * type LLMEventMap = {
+ *   AGENT_LLM_REQUEST: { requestId: string; prompt: string };
+ *   LLM_RESPONSE: { requestId: string; content: string; tokensUsed: number };
+ *   LLM_ERROR: { requestId: string; error: string };
+ * };
+ *
+ * const events: ServiceEvents<LLMEventMap> = getEventBus();
+ * events.emit('LLM_RESPONSE', { requestId: '1', content: '...', tokensUsed: 42 });
+ * ```
+ */
+interface ServiceEvents<EventMap extends Record<string, Record<string, unknown>>> {
+    emit<E extends keyof EventMap & string>(event: E, payload: EventMap[E]): void;
+    on<E extends keyof EventMap & string>(event: E, handler: (payload: EventMap[E]) => void): () => void;
+}
+/**
+ * Create a typed view of an untyped EventBus. Wraps the raw EventBus
+ * with compile-time type checking while keeping runtime behavior identical.
+ *
+ * @example
+ * ```typescript
+ * type LLMEventMap = {
+ *   LLM_RESPONSE: { requestId: string; content: string };
+ *   LLM_ERROR: { requestId: string; error: string };
+ * };
+ *
+ * const typedBus = createTypedEventBus<LLMEventMap>(getServerEventBus());
+ * typedBus.emit('LLM_RESPONSE', { requestId: '1', content: '...' }); // type-safe
+ * typedBus.on('LLM_ERROR', (payload) => { payload.error; }); // payload is typed
+ * ```
+ */
+declare function createTypedEventBus<EventMap extends Record<string, Record<string, unknown>>>(bus: {
+    emit(event: string, payload?: unknown, meta?: Record<string, unknown>): void;
+    on(event: string, handler: (payload: unknown, meta?: Record<string, unknown>) => void): () => void;
+}): ServiceEvents<EventMap>;
+/** Filter operator for store queries. */
+type StoreFilterOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "contains";
+/** A single filter clause for store queries. */
+interface StoreFilter<T> {
+    field: keyof T & string;
+    op: StoreFilterOp;
+    value: unknown;
+}
+/**
+ * Database abstraction boundary. Services receive `StoreContract<T>`,
+ * not raw database clients. Swappable per database engine.
+ *
+ * @example
+ * ```typescript
+ * interface LLMRequest { id: string; prompt: string; status: string }
+ *
+ * class FirestoreLLMRequestStore implements StoreContract<LLMRequest> {
+ *   async getById(id) { ... }
+ *   async create(data) { ... }
+ *   async update(id, data) { ... }
+ *   async delete(id) { ... }
+ *   async query(filters) { ... }
+ * }
+ * ```
+ */
+interface StoreContract<T extends {
+    id: string;
+}> {
+    getById(id: string): Promise<T | null>;
+    create(data: Omit<T, "id">): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T>;
+    delete(id: string): Promise<void>;
+    query(filters: StoreFilter<T>[]): Promise<T[]>;
+}
+/**
+ * Standardized singleton lifecycle. Replaces ad-hoc
+ * `let x = null; export function getX()` patterns.
+ *
+ * @example
+ * ```typescript
+ * const llmClient = createLazyService(() => new LLMClient({ apiKey: process.env.LLM_KEY }));
+ *
+ * // In request handler:
+ * const client = llmClient.get(); // created on first call, cached after
+ *
+ * // In test teardown:
+ * llmClient.reset(); // next get() creates a fresh instance
+ * ```
+ */
+interface LazyService<T> {
+    /** Get the singleton instance (creates on first call). */
+    get(): T;
+    /** Reset the singleton (next get() creates fresh). For test isolation. */
+    reset(): void;
+}
+/**
+ * Create a lazy singleton from a factory function.
+ */
+declare function createLazyService<T>(factory: () => T): LazyService<T>;
+
 /**
  * Shared Intermediate Representation Types
  *
@@ -701,4 +843,4 @@ declare function createResolvedField(field: {
 }): ResolvedField;
 declare function isResolvedIR(ir: unknown): ir is ResolvedIR;
 
-export { type AppSummary, BINDING_CONTEXT_RULES, BINDING_DOCS, type BindingContext, BindingSchema, type CategorizedRemovals, type ChangeAuthor, type ChangeSetDocument, type ChangeSummary, type CreateFlow, DEFAULT_INTERACTION_MODELS, type DeleteFlow, type EditFlow, type GitHubLink, type HistoryMeta, type InteractionModel, type InteractionModelInput, InteractionModelSchema, type ListInteraction, type OperatorName, type PageContentReduction, PatternTypeSchema, type ResolvedEntity, type ResolvedEntityBinding, type ResolvedField, type ResolvedIR, type ResolvedNavigation, type ResolvedPage, type ResolvedPattern, type ResolvedSection, type ResolvedSectionEvent, type ResolvedTrait, type ResolvedTraitBinding, type ResolvedTraitDataEntity, type ResolvedTraitEvent, type ResolvedTraitGuard, type ResolvedTraitListener, type ResolvedTraitState, type ResolvedTraitTick, type ResolvedTraitTransition, type ResolvedTraitUIBinding, SExpr, type SaveOptions, type SaveResult, type SchemaChange, type SnapshotDocument, type StatsView, type TransitionFrom, type ValidationDocument, type ValidationIssue, type ValidationMeta, type ValidationResults, type ViewFlow, createEmptyResolvedPage, createEmptyResolvedTrait, createResolvedField, getAllOperators, getAllPatternTypes, getBindingExamples, getInteractionModelForDomain, inferTsType, isResolvedIR, validateBindingInContext };
+export { type AppSummary, BINDING_CONTEXT_RULES, BINDING_DOCS, type BindingContext, BindingSchema, type CategorizedRemovals, type ChangeAuthor, type ChangeSetDocument, type ChangeSummary, type CreateFlow, DEFAULT_INTERACTION_MODELS, type DeleteFlow, type EditFlow, type GitHubLink, type HistoryMeta, type InteractionModel, type InteractionModelInput, InteractionModelSchema, type LazyService, type ListInteraction, type OperatorName, type PageContentReduction, PatternTypeSchema, type ResolvedEntity, type ResolvedEntityBinding, type ResolvedField, type ResolvedIR, type ResolvedNavigation, type ResolvedPage, type ResolvedPattern, type ResolvedSection, type ResolvedSectionEvent, type ResolvedTrait, type ResolvedTraitBinding, type ResolvedTraitDataEntity, type ResolvedTraitEvent, type ResolvedTraitGuard, type ResolvedTraitListener, type ResolvedTraitState, type ResolvedTraitTick, type ResolvedTraitTransition, type ResolvedTraitUIBinding, SExpr, type SaveOptions, type SaveResult, type SchemaChange, type ServiceAction, type ServiceContract, type ServiceEvents, type SnapshotDocument, type StatsView, type StoreContract, type StoreFilter, type StoreFilterOp, type TransitionFrom, type ValidationDocument, type ValidationIssue, type ValidationMeta, type ValidationResults, type ViewFlow, createEmptyResolvedPage, createEmptyResolvedTrait, createLazyService, createResolvedField, createTypedEventBus, getAllOperators, getAllPatternTypes, getBindingExamples, getInteractionModelForDomain, inferTsType, isResolvedIR, validateBindingInContext };

package/dist/types/index.js

@@ -1124,6 +1124,32 @@ function getAllPatternTypes() {
   return [...PATTERN_TYPES];
 }
 
+// src/service-types.ts
+function createTypedEventBus(bus) {
+  return {
+    emit(event, payload) {
+      bus.emit(event, payload);
+    },
+    on(event, handler) {
+      return bus.on(event, handler);
+    }
+  };
+}
+function createLazyService(factory) {
+  let instance = null;
+  return {
+    get() {
+      if (instance === null) {
+        instance = factory();
+      }
+      return instance;
+    },
+    reset() {
+      instance = null;
+    }
+  };
+}
+
 // src/types/ir.ts
 function createEmptyResolvedTrait(name, source) {
   return {
@@ -1186,6 +1212,6 @@ function isResolvedIR(ir) {
   return typeof r.appName === "string" && r.traits instanceof Map && r.pages instanceof Map;
 }
 
-export { AGENT_DOMAIN_CATEGORIES, ALLOWED_CUSTOM_COMPONENTS, AgentDomainCategorySchema, AnimationDefSchema, AssetMapSchema, AssetMappingSchema, BINDING_CONTEXT_RULES, BINDING_DOCS, BindingSchema, CORE_BINDINGS, ComputedEventContractSchema, ComputedEventListenerSchema, CustomPatternDefinitionSchema, CustomPatternMapSchema, DEFAULT_INTERACTION_MODELS, DesignPreferencesSchema, DesignTokensSchema, DomainCategorySchema, DomainContextSchema, DomainVocabularySchema, ENTITY_ROLES, EffectSchema, EntityFieldSchema, EntityPersistenceSchema, EntityRefSchema, EntityRefStringSchema, EntityRoleSchema, EntitySchema, EntitySemanticRoleSchema, EventListenerSchema, EventPayloadFieldSchema, EventSchema, EventScopeSchema, EventSemanticRoleSchema, EventSourceSchema, ExpressionSchema, FieldFormatSchema, FieldSchema, FieldTypeSchema, GAME_TYPES, GameSubCategorySchema, GameTypeSchema, GuardSchema, InteractionModelSchema, McpServiceDefSchema, NodeClassificationSchema, OrbitalConfigSchema, OrbitalDefinitionSchema, OrbitalEntitySchema, OrbitalPageSchema, OrbitalPageStrictSchema, OrbitalSchemaSchema, OrbitalTraitRefSchema, OrbitalUnitSchema, OrbitalSchema as OrbitalZodSchema, PageRefObjectSchema, PageRefSchema, PageRefStringSchema, PageSchema, PageTraitRefSchema, PatternTypeSchema, PayloadFieldSchema, RelatedLinkSchema, RelationConfigSchema, RequiredFieldSchema, ResolvedAssetSchema, RestAuthConfigSchema, RestServiceDefSchema, SERVICE_TYPES, SExprAtomSchema, SExprSchema, SemanticAssetRefSchema, ServiceDefinitionSchema, ServiceRefSchema, ServiceRefStringSchema, ServiceTypeSchema, SocketEventsSchema, SocketServiceDefSchema, StateMachineSchema, StateSchema, StateSemanticRoleSchema, SuggestedGuardSchema, ThemeDefinitionSchema, ThemeRefSchema, ThemeRefStringSchema, ThemeTokensSchema, ThemeVariantSchema, TraitCategorySchema, TraitDataEntitySchema, TraitEntityFieldSchema, TraitEventContractSchema, TraitEventListenerSchema, TraitRefSchema, TraitReferenceSchema, TraitSchema, TraitTickSchema, TransitionSchema, UISlotSchema, UI_SLOTS, UXHintsSchema, UseDeclarationSchema, UserPersonaSchema, VISUAL_STYLES, ViewTypeSchema, VisualStyleSchema, callService, collectBindings, createAssetKey, createEmptyResolvedPage, createEmptyResolvedTrait, createResolvedField, deriveCollection, despawn, doEffects, emit, findService, getAllOperators, getAllPatternTypes, getArgs, getBindingExamples, getDefaultAnimationsForRole, getInteractionModelForDomain, getOperator, getServiceNames, getTraitConfig, getTraitName, hasService, inferTsType, isBinding, isCircuitEvent, isEffect, isEntityReference, isImportedTraitRef, isInlineTrait, isMcpService, isOrbitalDefinition, isPageReference, isPageReferenceObject, isPageReferenceString, isResolvedIR, isRestService, isRuntimeEntity, isSExpr, isSExprAtom, isSExprCall, isSExprEffect, isServiceReference, isSingletonEntity, isSocketService, isThemeReference, isValidBinding, navigate, normalizeTraitRef, notify, parseAssetKey, parseBinding, parseEntityRef, parseImportedTraitRef, parseOrbitalSchema, parsePageRef, parseServiceRef, persist, renderUI, safeParseOrbitalSchema, set, sexpr, spawn, validateAssetAnimations, validateBindingInContext, walkSExpr };
+export { AGENT_DOMAIN_CATEGORIES, ALLOWED_CUSTOM_COMPONENTS, AgentDomainCategorySchema, AnimationDefSchema, AssetMapSchema, AssetMappingSchema, BINDING_CONTEXT_RULES, BINDING_DOCS, BindingSchema, CORE_BINDINGS, ComputedEventContractSchema, ComputedEventListenerSchema, CustomPatternDefinitionSchema, CustomPatternMapSchema, DEFAULT_INTERACTION_MODELS, DesignPreferencesSchema, DesignTokensSchema, DomainCategorySchema, DomainContextSchema, DomainVocabularySchema, ENTITY_ROLES, EffectSchema, EntityFieldSchema, EntityPersistenceSchema, EntityRefSchema, EntityRefStringSchema, EntityRoleSchema, EntitySchema, EntitySemanticRoleSchema, EventListenerSchema, EventPayloadFieldSchema, EventSchema, EventScopeSchema, EventSemanticRoleSchema, EventSourceSchema, ExpressionSchema, FieldFormatSchema, FieldSchema, FieldTypeSchema, GAME_TYPES, GameSubCategorySchema, GameTypeSchema, GuardSchema, InteractionModelSchema, McpServiceDefSchema, NodeClassificationSchema, OrbitalConfigSchema, OrbitalDefinitionSchema, OrbitalEntitySchema, OrbitalPageSchema, OrbitalPageStrictSchema, OrbitalSchemaSchema, OrbitalTraitRefSchema, OrbitalUnitSchema, OrbitalSchema as OrbitalZodSchema, PageRefObjectSchema, PageRefSchema, PageRefStringSchema, PageSchema, PageTraitRefSchema, PatternTypeSchema, PayloadFieldSchema, RelatedLinkSchema, RelationConfigSchema, RequiredFieldSchema, ResolvedAssetSchema, RestAuthConfigSchema, RestServiceDefSchema, SERVICE_TYPES, SExprAtomSchema, SExprSchema, SemanticAssetRefSchema, ServiceDefinitionSchema, ServiceRefSchema, ServiceRefStringSchema, ServiceTypeSchema, SocketEventsSchema, SocketServiceDefSchema, StateMachineSchema, StateSchema, StateSemanticRoleSchema, SuggestedGuardSchema, ThemeDefinitionSchema, ThemeRefSchema, ThemeRefStringSchema, ThemeTokensSchema, ThemeVariantSchema, TraitCategorySchema, TraitDataEntitySchema, TraitEntityFieldSchema, TraitEventContractSchema, TraitEventListenerSchema, TraitRefSchema, TraitReferenceSchema, TraitSchema, TraitTickSchema, TransitionSchema, UISlotSchema, UI_SLOTS, UXHintsSchema, UseDeclarationSchema, UserPersonaSchema, VISUAL_STYLES, ViewTypeSchema, VisualStyleSchema, callService, collectBindings, createAssetKey, createEmptyResolvedPage, createEmptyResolvedTrait, createLazyService, createResolvedField, createTypedEventBus, deriveCollection, despawn, doEffects, emit, findService, getAllOperators, getAllPatternTypes, getArgs, getBindingExamples, getDefaultAnimationsForRole, getInteractionModelForDomain, getOperator, getServiceNames, getTraitConfig, getTraitName, hasService, inferTsType, isBinding, isCircuitEvent, isEffect, isEntityReference, isImportedTraitRef, isInlineTrait, isMcpService, isOrbitalDefinition, isPageReference, isPageReferenceObject, isPageReferenceString, isResolvedIR, isRestService, isRuntimeEntity, isSExpr, isSExprAtom, isSExprCall, isSExprEffect, isServiceReference, isSingletonEntity, isSocketService, isThemeReference, isValidBinding, navigate, normalizeTraitRef, notify, parseAssetKey, parseBinding, parseEntityRef, parseImportedTraitRef, parseOrbitalSchema, parsePageRef, parseServiceRef, persist, renderUI, safeParseOrbitalSchema, set, sexpr, spawn, validateAssetAnimations, validateBindingInContext, walkSExpr };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map