@dotdo/do 0.1.0

package/dist/types/cascade.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Cascade Types - Relation Operators for Post-Generation Linking
+ *
+ * Every DO natively supports four relation operators for post-generation linking:
+ *
+ * | Operator | Type             | Action                                    |
+ * |----------|------------------|-------------------------------------------|
+ * | `->`     | Forward Insert   | Create entity, link TO it                 |
+ * | `~>`     | Forward Search   | Vector search existing, link TO it        |
+ * | `<-`     | Backward Insert  | Create entity, link FROM it (it owns us)  |
+ * | `<~`     | Backward Search  | Vector search existing, link FROM it      |
+ *
+ * Example Schema:
+ * ```typescript
+ * const CustomerSchema = {
+ *   $type: 'Customer',
+ *   company: '~>Company',                    // Search for matching Company
+ *   industry: '<~Industry|Sector',           // Search Industry, fallback to Sector
+ *   contacts: ['->Contact'],                 // Create Contact entities
+ *   owner: '<-SalesRep',                     // SalesRep owns this Customer
+ * }
+ *
+ * const StartupSchema = {
+ *   $type: 'Startup',
+ *   idea: 'What is the idea? <-Idea',        // Idea entity owns this Startup
+ *   founders: ['Who are founders? ->Founder'],
+ *   customer: '~>IdealCustomerProfile',
+ * }
+ * ```
+ *
+ * These are DO-level primitives. Applications define their own cascade stages
+ * and generation pipelines using these operators.
+ */
+/**
+ * Relation operator type
+ *
+ * These define how entities are linked after AI generation:
+ * - Forward (`->`, `~>`): Current entity links TO target
+ * - Backward (`<-`, `<~`): Target entity links FROM current (target owns current)
+ * - Insert (`->`, `<-`): Create new entity
+ * - Search (`~>`, `<~`): Vector search existing entities
+ */
+export type RelationOperator = '->' | '~>' | '<-' | '<~';
+/**
+ * Relation direction
+ */
+export type RelationDirection = 'Forward' | 'Backward';
+/**
+ * Relation method
+ */
+export type RelationMethod = 'Insert' | 'Search';
+/**
+ * Parse relation operator into direction and method
+ */
+export declare function parseRelationOperator(op: RelationOperator): {
+    direction: RelationDirection;
+    method: RelationMethod;
+};
+/**
+ * Relation field definition in schema
+ *
+ * Format: "prompt text <operator>TargetType|Fallback1|Fallback2"
+ *
+ * Examples:
+ * - 'Who are they? <~Occupation|Role|JobType'  - Search with fallbacks
+ * - '->Founder'                                 - Insert new Founder
+ * - '<-Idea'                                    - Backward link from Idea
+ * - '~>Company?'                                - Optional search
+ * - '->Contact[]'                               - Array of inserts
+ */
+export interface RelationFieldDefinition {
+    /** The prompt/description for AI generation */
+    prompt?: string;
+    /** Relation operator */
+    operator: RelationOperator;
+    /** Target type(s) - first is primary, rest are fallbacks */
+    targets: string[];
+    /** Is this an array relation? */
+    isArray: boolean;
+    /** Is this optional? */
+    isOptional: boolean;
+}
+/**
+ * Parse a relation field string
+ *
+ * @example
+ * parseRelationField('Who are they? <~Occupation|Role')
+ * // { prompt: 'Who are they?', operator: '<~', targets: ['Occupation', 'Role'], isArray: false, isOptional: false }
+ *
+ * parseRelationField('->Founder[]')
+ * // { operator: '->', targets: ['Founder'], isArray: true, isOptional: false }
+ */
+export declare function parseRelationField(field: string): RelationFieldDefinition | null;
+/**
+ * Check if a field value is a relation field
+ */
+export declare function isRelationField(value: unknown): boolean;
+/**
+ * Stored relation (in _rels table)
+ *
+ * All relations are stored in a unified table for efficient querying
+ */
+export interface StoredRelation {
+    /** Relation ID */
+    id: string;
+    /** Relation type */
+    relType: 'Forward' | 'Backward' | 'FuzzyForward' | 'FuzzyBackward';
+    /** Relation name (field name in schema) */
+    relName: string;
+    /** Source collection/type */
+    fromCollection: string;
+    /** Source entity ID */
+    fromId: string;
+    /** Target collection/type */
+    toCollection: string;
+    /** Target entity ID */
+    toId: string;
+    /** Human-readable label (usually target's title) */
+    label?: string;
+    /** Source shard (for cross-shard relations) */
+    fromShard?: string;
+    /** Target shard (for cross-shard relations) */
+    toShard?: string;
+    /** Ordinal for ordered relations */
+    ordinal: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Timestamps */
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Relation manager interface (DO-level)
+ *
+ * Every DO has a built-in relation manager for handling cascade relations
+ */
+export interface RelationManager {
+    /** Create a relation */
+    create(rel: Omit<StoredRelation, 'id' | 'createdAt' | 'updatedAt'>): Promise<StoredRelation>;
+    /** Create bidirectional relation (forward + inverse) */
+    createBidirectional(rel: Omit<StoredRelation, 'id' | 'createdAt' | 'updatedAt'>, inverseRelName: string): Promise<[StoredRelation, StoredRelation]>;
+    /** Get outgoing relations from an entity */
+    getOutgoing(collection: string, docId: string, relName?: string): Promise<StoredRelation[]>;
+    /** Get incoming relations to an entity */
+    getIncoming(collection: string, docId: string, relName?: string): Promise<StoredRelation[]>;
+    /** Get all relations for an entity (both directions) */
+    getAll(collection: string, docId: string): Promise<StoredRelation[]>;
+    /** Delete a relation */
+    delete(relId: string): Promise<boolean>;
+    /** Delete all relations for an entity */
+    deleteAll(collection: string, docId: string): Promise<number>;
+    /** Check if relation exists */
+    exists(fromCollection: string, fromId: string, toCollection: string, toId: string): Promise<boolean>;
+    /** Count relations */
+    count(collection: string, docId: string, direction?: 'Outgoing' | 'Incoming'): Promise<number>;
+    /** Update relation metadata */
+    updateMetadata(relId: string, metadata: Record<string, unknown>): Promise<StoredRelation>;
+    /** Update ordinal (for reordering) */
+    updateOrdinal(relId: string, ordinal: number): Promise<StoredRelation>;
+}
+/**
+ * Cascade post-processor interface
+ *
+ * After AI generation, the cascade processor handles relation linking
+ */
+export interface CascadeProcessor {
+    /**
+     * Process cascade relations for a generated entity
+     *
+     * For each field with a relation operator:
+     * - `->`: Create new entity, link TO it
+     * - `~>`: Vector search, link TO best match
+     * - `<-`: Create new entity, link FROM it
+     * - `<~`: Vector search, link FROM best match
+     */
+    process(sourceType: string, sourceId: string, generatedData: Record<string, unknown>, schema: Record<string, string | string[]>): Promise<CascadeResult>;
+    /**
+     * Process a single relation field
+     */
+    processField(sourceType: string, sourceId: string, fieldName: string, fieldValue: unknown, fieldDef: RelationFieldDefinition): Promise<CascadeFieldResult>;
+}
+/**
+ * Result of cascade processing
+ */
+export interface CascadeResult {
+    /** Entities created during cascade */
+    created: Array<{
+        type: string;
+        id: string;
+        data?: unknown;
+    }>;
+    /** Relations created */
+    relations: StoredRelation[];
+    /** Errors encountered */
+    errors: CascadeError[];
+}
+/**
+ * Result of processing a single field
+ */
+export interface CascadeFieldResult {
+    /** Entity created (if insert) */
+    created?: {
+        type: string;
+        id: string;
+        data?: unknown;
+    };
+    /** Entity matched (if search) */
+    matched?: {
+        type: string;
+        id: string;
+        score?: number;
+    };
+    /** Relation created */
+    relation?: StoredRelation;
+    /** Error if failed */
+    error?: CascadeError;
+}
+/**
+ * Cascade error
+ */
+export interface CascadeError {
+    field: string;
+    message: string;
+    targetType?: string;
+    code?: 'NotFound' | 'Ambiguous' | 'Invalid' | 'Failed';
+}
+/**
+ * Entity schema with relation fields
+ *
+ * Fields can be:
+ * - Primitive: 'string', 'number', 'boolean', etc.
+ * - Prompt: 'What is the name?'
+ * - Relation: '->TargetType' or 'prompt ~>TargetType|Fallback'
+ * - Array relation: ['->TargetType']
+ */
+export type EntitySchema = Record<string, SchemaField>;
+export type SchemaField = string | [string] | SchemaFieldDefinition;
+export interface SchemaFieldDefinition {
+    /** Field type or prompt */
+    type: string;
+    /** Description */
+    description?: string;
+    /** Is required */
+    required?: boolean;
+    /** Default value */
+    default?: unknown;
+    /** Relation definition (if relation field) */
+    relation?: RelationFieldDefinition;
+}
+/**
+ * Cascade configuration (application-defined)
+ *
+ * Applications define their own cascade stages and pipelines.
+ * This is a generic configuration interface.
+ */
+export interface CascadeConfig {
+    /** Maximum depth for recursive cascades */
+    maxDepth?: number;
+    /** Concurrency for parallel processing */
+    concurrency?: number;
+    /** Retry policy */
+    retryPolicy?: {
+        maxAttempts: number;
+        backoff: 'Linear' | 'Exponential';
+        initialDelay?: number;
+    };
+    /** Rate limiting */
+    rateLimit?: {
+        requestsPerMinute: number;
+        tokensPerMinute?: number;
+    };
+    /** Vector search options */
+    vectorSearch?: {
+        topK?: number;
+        scoreThreshold?: number;
+    };
+    /** Checkpoint during long cascades */
+    checkpoint?: boolean;
+    /** Checkpoint interval (number of entities) */
+    checkpointInterval?: number;
+}
+/**
+ * Cascade event types for observability
+ */
+export type CascadeEvent = {
+    type: 'Cascade.Entity.created';
+    payload: {
+        type: string;
+        id: string;
+    };
+} | {
+    type: 'Cascade.Entity.matched';
+    payload: {
+        type: string;
+        id: string;
+        score: number;
+    };
+} | {
+    type: 'Cascade.Relation.created';
+    payload: {
+        relId: string;
+        from: string;
+        to: string;
+    };
+} | {
+    type: 'Cascade.Error.occurred';
+    payload: CascadeError;
+} | {
+    type: 'Cascade.Processing.started';
+    payload: {
+        sourceType: string;
+        sourceId: string;
+    };
+} | {
+    type: 'Cascade.Processing.completed';
+    payload: {
+        sourceType: string;
+        sourceId: string;
+        created: number;
+        relations: number;
+    };
+};
+//# sourceMappingURL=cascade.d.ts.map

package/dist/types/cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../types/cascade.ts"],"names":[],"mappings":"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"}

package/dist/types/cascade.js

@@ -0,0 +1,82 @@
+/**
+ * Cascade Types - Relation Operators for Post-Generation Linking
+ *
+ * Every DO natively supports four relation operators for post-generation linking:
+ *
+ * | Operator | Type             | Action                                    |
+ * |----------|------------------|-------------------------------------------|
+ * | `->`     | Forward Insert   | Create entity, link TO it                 |
+ * | `~>`     | Forward Search   | Vector search existing, link TO it        |
+ * | `<-`     | Backward Insert  | Create entity, link FROM it (it owns us)  |
+ * | `<~`     | Backward Search  | Vector search existing, link FROM it      |
+ *
+ * Example Schema:
+ * ```typescript
+ * const CustomerSchema = {
+ *   $type: 'Customer',
+ *   company: '~>Company',                    // Search for matching Company
+ *   industry: '<~Industry|Sector',           // Search Industry, fallback to Sector
+ *   contacts: ['->Contact'],                 // Create Contact entities
+ *   owner: '<-SalesRep',                     // SalesRep owns this Customer
+ * }
+ *
+ * const StartupSchema = {
+ *   $type: 'Startup',
+ *   idea: 'What is the idea? <-Idea',        // Idea entity owns this Startup
+ *   founders: ['Who are founders? ->Founder'],
+ *   customer: '~>IdealCustomerProfile',
+ * }
+ * ```
+ *
+ * These are DO-level primitives. Applications define their own cascade stages
+ * and generation pipelines using these operators.
+ */
+/**
+ * Parse relation operator into direction and method
+ */
+export function parseRelationOperator(op) {
+    switch (op) {
+        case '->': return { direction: 'Forward', method: 'Insert' };
+        case '~>': return { direction: 'Forward', method: 'Search' };
+        case '<-': return { direction: 'Backward', method: 'Insert' };
+        case '<~': return { direction: 'Backward', method: 'Search' };
+    }
+}
+/**
+ * Parse a relation field string
+ *
+ * @example
+ * parseRelationField('Who are they? <~Occupation|Role')
+ * // { prompt: 'Who are they?', operator: '<~', targets: ['Occupation', 'Role'], isArray: false, isOptional: false }
+ *
+ * parseRelationField('->Founder[]')
+ * // { operator: '->', targets: ['Founder'], isArray: true, isOptional: false }
+ */
+export function parseRelationField(field) {
+    // Match: optional prompt, operator, target types, optional array marker, optional marker
+    const match = field.match(/^(.*?)?\s*(->|~>|<-|<~)([A-Z][a-zA-Z0-9]*(?:\|[A-Z][a-zA-Z0-9]*)*)(\[\])?(\?)?$/);
+    if (!match)
+        return null;
+    const [, prompt, operator, targetStr, arrayMarker, optionalMarker] = match;
+    const targets = targetStr.split('|');
+    return {
+        prompt: prompt?.trim() || undefined,
+        operator: operator,
+        targets,
+        isArray: !!arrayMarker,
+        isOptional: !!optionalMarker,
+    };
+}
+/**
+ * Check if a field value is a relation field
+ */
+export function isRelationField(value) {
+    if (typeof value === 'string') {
+        return /->|~>|<-|<~/.test(value);
+    }
+    if (Array.isArray(value) && value.length === 1 && typeof value[0] === 'string') {
+        return /->|~>|<-|<~/.test(value[0]);
+    }
+    return false;
+}
+//# sourceMappingURL=cascade.js.map

package/dist/types/cascade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.js","sourceRoot":"","sources":["../../types/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA6BH;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAoB;IAIxD,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;QAC5D,KAAK,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;QAC5D,KAAK,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;QAC7D,KAAK,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;IAC/D,CAAC;AACH,CAAC;AA+BD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,yFAAyF;IACzF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,iFAAiF,CAAC,CAAA;IAC5G,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IAEvB,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,CAAC,GAAG,KAAK,CAAA;IAC1E,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEpC,OAAO;QACL,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,SAAS;QACnC,QAAQ,EAAE,QAA4B;QACtC,OAAO;QACP,OAAO,EAAE,CAAC,CAAC,WAAW;QACtB,UAAU,EAAE,CAAC,CAAC,cAAc;KAC7B,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAClC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/E,OAAO,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACrC,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}