@aigne/afs-world-mapping 1.11.0-beta.6

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+import { AFSEntry, AFSModule } from "@aigne/afs";
+
+//#region src/binding/types.d.ts
+/**
+ * Provider-Agnostic Binding Types
+ *
+ * Declares how a world schema maps to source AFS paths.
+ * No backend-specific details — only path templates and field renames.
+ */
+/** Per-kind mapping configuration */
+interface KindMapping {
+  /** Override source path for this kind (defaults to WorldBinding.source) */
+  source?: string;
+  /** Source path template (e.g., /issues/{number}) */
+  path?: string;
+  /** World field name → source field name rename map */
+  fieldMap?: Record<string, string>;
+}
+/** Top-level binding: declares source AFS and per-kind overrides */
+interface WorldBinding {
+  /** Default source AFS path prefix */
+  source: string;
+  /** Per-kind mapping overrides */
+  mappings?: Record<string, KindMapping>;
+}
+//#endregion
+//#region src/capability.d.ts
+type MutateAction = "create" | "update" | "delete" | "exec";
+interface MutateResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+interface WorldStatus {
+  loaded: boolean;
+  loadedAt?: Date;
+  schemaPath?: string;
+  bindingPath?: string;
+  compiled: boolean;
+  error?: string;
+  stats?: {
+    kinds: number;
+    routes: number;
+    operations: number;
+  };
+}
+interface BackendOp {
+  type: "sql" | "http" | "graphql" | "mcp-tool" | "custom";
+  operation: unknown;
+  params?: Record<string, unknown>;
+}
+interface ProjectionContext {
+  path: string;
+  kind: string;
+  pathParams: Record<string, string>;
+}
+interface AFSWorldMappingCapable {
+  loadWorld(schemaPath: string, bindingPath: string): Promise<void>;
+  reloadWorld(): Promise<void>;
+  getWorldStatus(): WorldStatus;
+  resolve(path: string): BackendOp | null;
+  project(backendData: unknown, context: ProjectionContext): AFSEntry[];
+  mutate(path: string, action: MutateAction, payload: unknown): Promise<MutateResult>;
+}
+declare function isWorldMappingCapable(module: AFSModule): module is AFSModule & AFSWorldMappingCapable;
+//#endregion
+//#region src/schema/types.d.ts
+/**
+ * World Schema DSL type definitions.
+ *
+ * These types represent the structure of a World Schema YAML file.
+ * They are purely declarative — no backend-specific details.
+ */
+/** Primitive field types + parameterized types (enum, ref, list) */
+type FieldType = string;
+/** Relation type — always list:KindName */
+type RelationType = string;
+interface UniqueConstraint {
+  unique: string[];
+}
+interface RequiredConstraint {
+  required: string[];
+}
+type Constraint = UniqueConstraint | RequiredConstraint;
+interface ComputedFieldDef {
+  expr: string;
+}
+interface RepresentDef {
+  format: string;
+  template: string;
+}
+interface KindDef {
+  key: string;
+  path: string;
+  fields: Record<string, FieldType>;
+  relations?: Record<string, RelationType>;
+  indexes?: string[][];
+  constraints?: Constraint[];
+  computed?: Record<string, ComputedFieldDef>;
+  represent?: Record<string, RepresentDef>;
+  validate?: Array<{
+    expr: string;
+    error: string;
+  }>;
+}
+interface WorldSchema {
+  world: string;
+  version: string;
+  description?: string;
+  kinds: Record<string, KindDef>;
+}
+//#endregion
+//#region src/compiler.d.ts
+/** Result of resolving a world path */
+interface TrieMatch {
+  kind: string;
+  params: Record<string, string>;
+  isCollection: boolean;
+}
+/** Compiled kind metadata */
+interface CompiledKind {
+  key: string;
+  source: string;
+  fieldMap: Record<string, string>;
+}
+/** Result of compilation */
+interface CompiledMapping {
+  world: string;
+  version: string;
+  resolve: (path: string) => TrieMatch | null;
+  kinds: Record<string, CompiledKind>;
+}
+declare class WorldCompiler {
+  compile(schema: WorldSchema | any, binding: WorldBinding): CompiledMapping;
+  private validateIdentifier;
+  private validateFieldType;
+  private buildPathTrie;
+  private resolvePath;
+}
+//#endregion
+//#region src/core.d.ts
+declare class WorldMappingCore {
+  readonly schema: WorldSchema;
+  readonly binding: WorldBinding;
+  private compiled;
+  constructor(schema: WorldSchema | any, binding: WorldBinding);
+  /** Resolve a target world path to kind + params + isCollection */
+  resolve(path: string): TrieMatch | null;
+  /** Translate a TrieMatch to a source AFS path */
+  translatePath(match: TrieMatch): string;
+  /** Project source fields → world fields (read direction) */
+  projectFields(data: Record<string, unknown>, kindName: string, params?: Record<string, unknown>): Record<string, unknown>;
+  /** Cache for parsed expressions */
+  private exprCache;
+  private getCompiledExpr;
+  /** Reverse project world fields → source fields (write direction) */
+  reverseProjectFields(data: Record<string, unknown>, kindName: string): Record<string, unknown>;
+  /** Get kind metadata */
+  getKind(name: string): CompiledKind | undefined;
+  /** List all kind names */
+  getKindNames(): string[];
+  /** Validate data against kind's validation rules */
+  validate(data: Record<string, unknown>, kindName: string): {
+    valid: boolean;
+    errors: Array<{
+      expr: string;
+      error: string;
+    }>;
+  };
+  /** Render a representation of data for a kind in the given format */
+  getRepresentation(data: Record<string, unknown>, kindName: string, format: string): string | null;
+}
+//#endregion
+//#region src/module.d.ts
+/** Source AFS interface — minimal interface for delegation */
+interface AFSSource {
+  list(path: string, options?: unknown): Promise<{
+    list: unknown[];
+    total?: number;
+  }>;
+  read(path: string, options?: unknown): Promise<unknown>;
+  write?(path: string, content: unknown, options?: unknown): Promise<unknown>;
+  delete?(path: string, options?: unknown): Promise<unknown>;
+}
+/** Options for WorldMappingModule */
+interface WorldMappingModuleOptions {
+  schema: WorldSchema;
+  binding: WorldBinding;
+  source: AFSSource;
+}
+declare class WorldMappingModule {
+  readonly name: string;
+  readonly description: string;
+  readonly core: WorldMappingCore;
+  private source;
+  constructor(options: WorldMappingModuleOptions);
+  /** List entries at a world path */
+  list(path: string): Promise<{
+    list: unknown[];
+    total?: number;
+  }>;
+  /** Read a single entry at a world path */
+  read(path: string): Promise<unknown>;
+  /** Write an entry at a world path */
+  write(path: string, content: Record<string, unknown>): Promise<unknown>;
+  /** Delete an entry at a world path */
+  delete(path: string): Promise<unknown>;
+  /** Get kind names */
+  getKindNames(): string[];
+}
+//#endregion
+//#region src/with-world-mapping.d.ts
+/** Configuration for injecting world mapping into a provider */
+interface WorldMappingConfig {
+  schema: WorldSchema;
+  binding: WorldBinding;
+}
+/** Status of an applied world mapping */
+interface WorldMappingStatus {
+  schema: WorldSchema;
+  binding: WorldBinding;
+  kinds: string[];
+  appliedAt: Date;
+}
+/** Interface that providers implement to accept world mapping injection */
+interface WithWorldMapping {
+  applyWorldMapping(config: WorldMappingConfig): void;
+  getWorldMapping(): WorldMappingStatus | null;
+}
+/** Type guard: check if an object supports world mapping injection */
+declare function isWithWorldMapping(obj: unknown): obj is WithWorldMapping;
+/**
+ * Helper for providers implementing WithWorldMapping.
+ * Validates config, creates WorldMappingCore, returns the mapping state.
+ * Throws if already applied or config is invalid.
+ */
+declare function applyWorldMappingHelper(config: WorldMappingConfig, existing: {
+  core: WorldMappingCore;
+  status: WorldMappingStatus;
+} | null): {
+  core: WorldMappingCore;
+  status: WorldMappingStatus;
+};
+//#endregion
+export { type AFSSource, type CompiledKind, type CompiledMapping, type KindMapping, type TrieMatch, type WithWorldMapping, type WorldBinding, WorldCompiler, type WorldMappingConfig, WorldMappingCore, WorldMappingModule, type WorldMappingModuleOptions, type WorldMappingStatus, type WorldSchema, applyWorldMappingHelper, isWithWorldMapping, isWorldMappingCapable };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/binding/types.ts","../src/capability.ts","../src/schema/types.ts","../src/compiler.ts","../src/core.ts","../src/module.ts","../src/with-world-mapping.ts"],"mappings":"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"}