ai-database 2.1.1 → 2.3.0

package/dist/type-guards.js

@@ -0,0 +1,318 @@
+/**
+ * Type Guards for ai-promise-db.ts
+ *
+ * These type guards enable type-safe property access on proxy objects
+ * and entity markers, providing proper type narrowing.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Check if a value has entity marker properties ($type, $id, or $isArrayRelation).
+ *
+ * @example
+ * ```ts
+ * const value = someProxy.$type
+ * if (hasEntityMarker(value)) {
+ *   // value is now typed as EntityMarker
+ *   console.log(value.$type) // Safe access
+ * }
+ * ```
+ */
+export function hasEntityMarker(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        ('$type' in value || '$id' in value || '$isArrayRelation' in value));
+}
+/**
+ * Check if a value has a custom valueOf method that returns a string.
+ * This is used to detect thenable relation proxies that return IDs via valueOf().
+ *
+ * Note: We check if valueOf returns a string to distinguish from Object.prototype.valueOf
+ * which returns the object itself.
+ *
+ * @example
+ * ```ts
+ * if (isValueOfable(relationProxy)) {
+ *   const id = relationProxy.valueOf()
+ *   // id is now safely extracted
+ * }
+ * ```
+ */
+export function isValueOfable(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    // All objects have valueOf, but we check if it returns a string (custom implementation)
+    if ('valueOf' in value && typeof value.valueOf === 'function') {
+        const result = value.valueOf();
+        return typeof result === 'string';
+    }
+    return false;
+}
+/**
+ * Check if a value has an explicit $id property.
+ */
+export function hasId(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '$id' in value &&
+        typeof value['$id'] === 'string');
+}
+/**
+ * Check if an array has entity relation markers ($type or $isArrayRelation).
+ * These markers are added by the hydration system to array relations.
+ *
+ * @example
+ * ```ts
+ * if (isEntityArray(members)) {
+ *   // members is a relation array
+ *   const type = members.$type // Safe access
+ * }
+ * ```
+ */
+export function isEntityArray(value) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    // Check for $type or $isArrayRelation properties on the array
+    const arr = value;
+    return ((arr['$type'] !== undefined && typeof arr['$type'] === 'string') ||
+        arr['$isArrayRelation'] === true);
+}
+/**
+ * Check if a value is a non-null object (excluding arrays).
+ * Useful for narrowing before accessing properties.
+ */
+export function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Check if an array contains relation elements (objects with $type markers).
+ */
+export function hasRelationElements(arr) {
+    return arr.some((v) => {
+        if (v === null || typeof v !== 'object') {
+            return false;
+        }
+        const obj = v;
+        return obj['$type'] !== undefined;
+    });
+}
+// =============================================================================
+// Extraction Functions
+// =============================================================================
+/**
+ * Extract an entity ID from various sources.
+ *
+ * Supports:
+ * - String IDs (returned as-is)
+ * - Objects with valueOf() returning string (thenable proxies)
+ * - Objects with $id property (entities)
+ * - Objects with id property (generic objects)
+ *
+ * @example
+ * ```ts
+ * // Works with strings
+ * extractEntityId('user-123') // 'user-123'
+ *
+ * // Works with thenable proxies
+ * extractEntityId(post.author) // 'author-id' via valueOf()
+ *
+ * // Works with entities
+ * extractEntityId(user) // user.$id
+ * ```
+ */
+export function extractEntityId(value) {
+    // Handle null/undefined
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    // Handle string directly
+    if (typeof value === 'string') {
+        return value;
+    }
+    // Handle objects
+    if (typeof value === 'object') {
+        const obj = value;
+        // Try valueOf() first (thenable proxies) - check if it returns a string
+        if ('valueOf' in obj && typeof obj.valueOf === 'function') {
+            const val = obj.valueOf();
+            if (typeof val === 'string') {
+                return val;
+            }
+        }
+        // Try $id property (entity marker)
+        if ('$id' in obj && typeof obj['$id'] === 'string') {
+            return obj['$id'];
+        }
+        // Try plain id property (generic object)
+        if ('id' in obj && typeof obj['id'] === 'string') {
+            return obj['id'];
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract the $type marker from an entity or relation proxy.
+ * Uses direct property access to handle proxy objects that may not expose the 'in' trap.
+ *
+ * @example
+ * ```ts
+ * const entity = { $type: 'User', name: 'John' }
+ * extractMarkerType(entity) // 'User'
+ * ```
+ */
+export function extractMarkerType(value) {
+    if (value === null || typeof value !== 'object') {
+        return undefined;
+    }
+    const obj = value;
+    const type = obj['$type'];
+    if (type !== undefined && typeof type === 'string') {
+        return type;
+    }
+    return undefined;
+}
+/**
+ * Extract $type from an array relation.
+ */
+export function extractArrayRelationType(arr) {
+    if (isEntityArray(arr) && typeof arr.$type === 'string') {
+        return arr.$type;
+    }
+    return undefined;
+}
+/**
+ * Safely access a property on an unknown value.
+ * Returns undefined if the value is not an object or the property doesn't exist.
+ */
+export function safeGet(value, key) {
+    if (isPlainObject(value)) {
+        return value[key];
+    }
+    return undefined;
+}
+// =============================================================================
+// Type Assertion Helpers
+// =============================================================================
+/**
+ * Assert that a value is a record (for use after type narrowing).
+ * Use this after verifying that a value is an object to get proper type inference.
+ */
+export function asRecord(value) {
+    return value;
+}
+/**
+ * Assert that a callback is properly typed.
+ * Used when the callback signature is known but TypeScript can't infer it.
+ */
+export function asCallback(fn) {
+    return fn;
+}
+/**
+ * Assert that a predicate is properly typed for array filter operations.
+ * Used when TypeScript can't infer the exact array element type.
+ */
+export function asPredicate(fn) {
+    return fn;
+}
+/**
+ * Assert that a comparator is properly typed for array sort operations.
+ * Used when TypeScript can't infer the exact array element type.
+ */
+export function asComparator(fn) {
+    return fn;
+}
+/**
+ * Type-safe access to symbol-keyed properties on objects.
+ * Used in proxy handlers where we need to access symbol properties.
+ */
+export function getSymbolProperty(obj, sym) {
+    return obj[sym];
+}
+/**
+ * Cast an item to the expected type.
+ * Used when the item type is known but TypeScript sees it as unknown.
+ */
+export function asItem(value) {
+    return value;
+}
+// =============================================================================
+// Draft/Resolve Type Guards
+// =============================================================================
+/**
+ * Check if an object is in draft phase.
+ * Draft objects have $phase === 'draft' and may have $refs.
+ */
+export function isDraft(value) {
+    return isPlainObject(value) && value['$phase'] === 'draft';
+}
+/**
+ * Check if an object is in resolved phase.
+ * Resolved objects have $phase === 'resolved'.
+ */
+export function isResolved(value) {
+    return isPlainObject(value) && value['$phase'] === 'resolved';
+}
+/**
+ * Extract $refs from a draft object safely.
+ * Returns undefined if the value is not a draft or has no $refs.
+ */
+export function extractRefs(value) {
+    if (isDraft(value) && isPlainObject(value['$refs'])) {
+        return value['$refs'];
+    }
+    return undefined;
+}
+/**
+ * Set a property on a Record safely.
+ * Used to avoid type assertions when setting properties on draft/resolved objects.
+ */
+export function setProperty(obj, key, value) {
+    obj[key] = value;
+}
+// =============================================================================
+// Dynamic Import Type Guards
+// =============================================================================
+/**
+ * Validate that a dynamic import result has the expected factory function.
+ * Provides type-safe access to dynamically imported modules.
+ *
+ * @example
+ * ```ts
+ * const module = await import('@mdxdb/fs')
+ * if (hasFactoryFunction(module, 'createFsProvider')) {
+ *   const provider = module.createFsProvider({ root: './content' })
+ * }
+ * ```
+ */
+export function hasFactoryFunction(module, functionName) {
+    return (module !== null &&
+        typeof module === 'object' &&
+        functionName in module &&
+        typeof module[functionName] === 'function');
+}
+/**
+ * Check if a value is a function.
+ * Useful for validating dynamic imports.
+ */
+export function isFunction(value) {
+    return typeof value === 'function';
+}
+// =============================================================================
+// Schema Type Guards
+// =============================================================================
+/**
+ * Safely access schema metadata fields.
+ * Returns undefined if the field is not present or not the expected type.
+ */
+export function getSchemaMetadata(schema, field) {
+    if (!schema || !isPlainObject(schema)) {
+        return undefined;
+    }
+    return schema[field];
+}
+//# sourceMappingURL=type-guards.js.map

package/dist/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../src/type-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuCH,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,OAAO,IAAI,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,kBAAkB,IAAI,KAAK,CAAC,CACpE,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,wFAAwF;IACxF,IAAI,SAAS,IAAI,KAAK,IAAI,OAAQ,KAAiC,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3F,MAAM,MAAM,GAAI,KAAqB,CAAC,OAAO,EAAE,CAAA;QAC/C,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAA;IACnC,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,KAAc;IAClC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,IAAI,KAAK;QACd,OAAQ,KAAiC,CAAC,KAAK,CAAC,KAAK,QAAQ,CAC9D,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAA;IACd,CAAC;IACD,8DAA8D;IAC9D,MAAM,GAAG,GAAG,KAAiD,CAAA;IAC7D,OAAO,CACL,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAChE,GAAG,CAAC,kBAAkB,CAAC,KAAK,IAAI,CACjC,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAc;IAChD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACxC,OAAO,KAAK,CAAA;QACd,CAAC;QACD,MAAM,GAAG,GAAG,CAA4B,CAAA;QACxC,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,CAAA;IACnC,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,wBAAwB;IACxB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,yBAAyB;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,iBAAiB;IACjB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAgC,CAAA;QAE5C,wEAAwE;QACxE,IAAI,SAAS,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YAC1D,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,EAAE,CAAA;YACzB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,GAAG,CAAA;YACZ,CAAC;QACH,CAAC;QAED,mCAAmC;QACnC,IAAI,KAAK,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAA;QACnB,CAAC;QAED,yCAAyC;QACzC,IAAI,IAAI,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAA;QAClB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAA;IAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,CAAA;IACzB,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACnD,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxD,OAAO,GAAG,CAAC,KAAK,CAAA;IAClB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAc,KAAc,EAAE,GAAW;IAC9D,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAkB,CAAA;IACpC,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,KAAgC,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,EAAiC;IAEjC,OAAO,EAAyC,CAAA;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,EAAuC;IAEvC,OAAO,EAA+C,CAAA;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,EAAwC;IAExC,OAAO,EAAsD,CAAA;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAc,GAAW,EAAE,GAAW;IACrE,OAAQ,GAA+B,CAAC,GAAG,CAAkB,CAAA;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAI,KAAc;IACtC,OAAO,KAAU,CAAA;AACnB,CAAC;AAED,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAA;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,KAAc;IAEd,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,UAAU,CAAA;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACpD,OAAO,KAAK,CAAC,OAAO,CAA4B,CAAA;IAClD,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAA4B,EAAE,GAAW,EAAE,KAAc;IACnF,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAClB,CAAC;AAED,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAe,EACf,YAAe;IAEf,OAAO,CACL,MAAM,KAAK,IAAI;QACf,OAAO,MAAM,KAAK,QAAQ;QAC1B,YAAY,IAAI,MAAM;QACtB,OAAQ,MAAkC,CAAC,YAAY,CAAC,KAAK,UAAU,CACxE,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAA;AACpC,CAAC;AAED,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA2C,EAC3C,KAAa;IAEb,IAAI,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAkB,CAAA;AACvC,CAAC"}

package/dist/types.d.ts

@@ -5,11 +5,16 @@
  * - Thing types (mdxld-based entity structure)
  * - Schema definition types
  * - Parsed schema types
- * - Noun & Verb semantic types
+ * - Noun & Verb semantic types (re-exported from @graphdl/core)
  *
  * @packageDocumentation
  */
 import type { MDXLD } from 'mdxld';
+import type { ParsedFieldType, RelationshipOperatorType } from '@org.ai/types';
+import type { Verb, VerbReverse, Noun, NounProperty, NounRelationship, TypeMeta, PrimitiveType } from '@graphdl/core';
+import { Verbs } from '@graphdl/core';
+export type { Verb, VerbReverse, Noun, NounProperty, NounRelationship, TypeMeta, PrimitiveType };
+export { Verbs };
 /**
  * Flat Thing shape with $-prefixed metadata fields
  * Used for JSON-LD compatible serialization
@@ -64,10 +69,6 @@ export declare function toExpanded(flat: ThingFlat): ThingExpanded;
  * Convert expanded thing to flat format
  */
 export declare function toFlat(expanded: ThingExpanded): ThingFlat;
-/**
- * Primitive field types
- */
-export type PrimitiveType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json' | 'markdown' | 'url';
 /**
  * A field definition can be:
  * - A primitive type: 'string', 'number', etc.
@@ -86,28 +87,37 @@ export type EntitySchema = Record<string, FieldDefinition>;
  */
 export type DatabaseSchema = Record<string, EntitySchema>;
 /**
- * Parsed field information
+ * Parsed field information.
+ * Extends ParsedFieldType from @org.ai/types with database-specific fields.
  */
-export interface ParsedField {
-    name: string;
-    type: string;
+export interface ParsedField extends ParsedFieldType {
+    /** Whether the field is an array (required, extends optional base field) */
     isArray: boolean;
+    /** Whether the field is optional (required, extends optional base field) */
     isOptional: boolean;
+    /** Whether this is a relationship field */
     isRelation: boolean;
-    relatedType?: string;
-    backref?: string;
     /** Operator used in field definition: ->, ~>, <-, <~ */
-    operator?: '->' | '~>' | '<-' | '<~';
+    operator?: RelationshipOperatorType;
     /** Direction of the relationship */
     direction?: 'forward' | 'backward';
     /** Match mode for the relationship */
     matchMode?: 'exact' | 'fuzzy';
     /** Natural language prompt before operator */
     prompt?: string;
-    /** Similarity threshold for fuzzy matching (0-1), parsed from ~>Type(0.9) syntax */
-    threshold?: number;
-    /** Union types for polymorphic references (e.g., ->A|B|C parses to ['A', 'B', 'C']) */
-    unionTypes?: string[];
+    /** Seed column mapping (e.g., '$.columnName') - maps source column to this field */
+    seedMapping?: string;
+}
+/**
+ * Seed configuration extracted from entity schema
+ */
+export interface SeedConfig {
+    /** URL to fetch seed data from */
+    url: string;
+    /** Column name to use as primary key (from $id field) */
+    idColumn: string;
+    /** Map of field names to source column names */
+    fieldMappings: Map<string, string>;
 }
 /**
  * Parsed entity with all fields including auto-generated backrefs
@@ -117,6 +127,8 @@ export interface ParsedEntity {
     fields: Map<string, ParsedField>;
     /** Original raw schema for accessing metadata like $fuzzyThreshold */
     schema?: EntitySchema;
+    /** Seed configuration if $seed is defined */
+    seedConfig?: SeedConfig;
 }
 /**
  * Fully parsed schema with bi-directional relationships resolved
@@ -124,235 +136,6 @@ export interface ParsedEntity {
 export interface ParsedSchema {
     entities: Map<string, ParsedEntity>;
 }
-/**
- * Verb conjugations and related forms
- *
- * Maps an action to its various grammatical forms and semantic relationships.
- *
- * @example
- * ```ts
- * const create: Verb = {
- *   action: 'create',      // Base form (imperative)
- *   actor: 'creator',      // Who does it (noun)
- *   act: 'creates',        // Present tense (3rd person)
- *   activity: 'creating',  // Gerund/continuous
- *   result: 'creation',    // Result noun
- *   reverse: {             // Passive/result properties
- *     at: 'createdAt',
- *     by: 'createdBy',
- *     in: 'createdIn',
- *     for: 'createdFor',
- *   },
- *   inverse: 'delete',     // Opposite action
- * }
- * ```
- */
-export interface Verb {
-    /** Base form / imperative (create, update, delete, publish) */
-    action: string;
-    /** Agent noun - who performs the action (creator, updater, author, publisher) */
-    actor?: string;
-    /** Present tense 3rd person singular (creates, updates, deletes, publishes) */
-    act?: string;
-    /** Present participle / gerund (creating, updating, deleting, publishing) */
-    activity?: string;
-    /** Result noun - what is produced (creation, update, deletion, publication) */
-    result?: string;
-    /** Reverse/passive forms - properties resulting from the action */
-    reverse?: {
-        /** Timestamp field (createdAt, updatedAt, deletedAt, publishedAt) */
-        at?: string;
-        /** Actor reference (createdBy, updatedBy, deletedBy, publishedBy) */
-        by?: string;
-        /** Location/context (createdIn, updatedIn, publishedIn) */
-        in?: string;
-        /** Purpose/target (createdFor, publishedFor) */
-        for?: string;
-        /** Additional reverse forms */
-        [key: string]: string | undefined;
-    };
-    /** Inverse action (create ↔ delete, publish ↔ unpublish, activate ↔ deactivate) */
-    inverse?: string;
-    /** Description of what this action does */
-    description?: string;
-}
-/**
- * Standard CRUD verbs with pre-defined conjugations
- */
-export declare const Verbs: {
-    readonly create: {
-        readonly action: "create";
-        readonly actor: "creator";
-        readonly act: "creates";
-        readonly activity: "creating";
-        readonly result: "creation";
-        readonly reverse: {
-            readonly at: "createdAt";
-            readonly by: "createdBy";
-            readonly in: "createdIn";
-            readonly for: "createdFor";
-        };
-        readonly inverse: "delete";
-    };
-    readonly update: {
-        readonly action: "update";
-        readonly actor: "updater";
-        readonly act: "updates";
-        readonly activity: "updating";
-        readonly result: "update";
-        readonly reverse: {
-            readonly at: "updatedAt";
-            readonly by: "updatedBy";
-        };
-    };
-    readonly delete: {
-        readonly action: "delete";
-        readonly actor: "deleter";
-        readonly act: "deletes";
-        readonly activity: "deleting";
-        readonly result: "deletion";
-        readonly reverse: {
-            readonly at: "deletedAt";
-            readonly by: "deletedBy";
-        };
-        readonly inverse: "create";
-    };
-    readonly publish: {
-        readonly action: "publish";
-        readonly actor: "publisher";
-        readonly act: "publishes";
-        readonly activity: "publishing";
-        readonly result: "publication";
-        readonly reverse: {
-            readonly at: "publishedAt";
-            readonly by: "publishedBy";
-        };
-        readonly inverse: "unpublish";
-    };
-    readonly archive: {
-        readonly action: "archive";
-        readonly actor: "archiver";
-        readonly act: "archives";
-        readonly activity: "archiving";
-        readonly result: "archive";
-        readonly reverse: {
-            readonly at: "archivedAt";
-            readonly by: "archivedBy";
-        };
-        readonly inverse: "unarchive";
-    };
-};
-/**
- * Noun definition - semantic description of an entity type
- *
- * Describes a Thing with its properties, relationships, available actions,
- * and metadata like singular/plural forms for natural language generation.
- *
- * @example
- * ```ts
- * const Post: Noun = {
- *   singular: 'post',
- *   plural: 'posts',
- *   description: 'A blog post or article',
- *
- *   properties: {
- *     title: { type: 'string', description: 'The post title' },
- *     content: { type: 'markdown', description: 'The post body' },
- *     status: { type: 'string', description: 'draft | published | archived' },
- *   },
- *
- *   relationships: {
- *     author: { type: 'Author', backref: 'posts', description: 'Who wrote this' },
- *     tags: { type: 'Tag[]', backref: 'posts', description: 'Categorization' },
- *   },
- *
- *   actions: ['create', 'update', 'delete', 'publish', 'archive'],
- *
- *   events: ['created', 'updated', 'deleted', 'published', 'archived'],
- * }
- * ```
- */
-export interface Noun {
-    /** Singular form (post, user, category) */
-    singular: string;
-    /** Plural form (posts, users, categories) */
-    plural: string;
-    /** Human-readable description */
-    description?: string;
-    /** Property definitions with descriptions */
-    properties?: Record<string, NounProperty>;
-    /** Relationship definitions with descriptions */
-    relationships?: Record<string, NounRelationship>;
-    /** Actions that can be performed on this noun (verbs) */
-    actions?: Array<string | Verb>;
-    /** Events that can occur to this noun */
-    events?: string[];
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Property definition within a Noun
- */
-export interface NounProperty {
-    /** Field type */
-    type: PrimitiveType | string;
-    /** Human-readable description (also used as generation prompt) */
-    description?: string;
-    /** Whether the field is optional */
-    optional?: boolean;
-    /** Whether the field is an array */
-    array?: boolean;
-    /** Default value */
-    default?: unknown;
-    /** Example values for documentation/generation */
-    examples?: unknown[];
-}
-/**
- * Relationship definition within a Noun
- */
-export interface NounRelationship {
-    /** Related entity type (e.g., 'Author', 'Tag[]') */
-    type: string;
-    /** Backref field name on the related entity */
-    backref?: string;
-    /** Human-readable description */
-    description?: string;
-    /** Whether this is a required relationship */
-    required?: boolean;
-}
-/**
- * Type metadata - automatically inferred from type name
- *
- * Available on every entity via `entity.$type` or `db.Post.$meta`
- */
-export interface TypeMeta {
-    /** Type name as defined in schema (e.g., 'Post', 'BlogPost') */
-    name: string;
-    /** Singular form (e.g., 'post', 'blog post') */
-    singular: string;
-    /** Plural form (e.g., 'posts', 'blog posts') */
-    plural: string;
-    /** URL-safe slug (e.g., 'post', 'blog-post') */
-    slug: string;
-    /** Plural slug (e.g., 'posts', 'blog-posts') */
-    slugPlural: string;
-    /** Creator relationship name */
-    creator: string;
-    /** Created timestamp field */
-    createdAt: string;
-    /** Created by field */
-    createdBy: string;
-    /** Updated timestamp field */
-    updatedAt: string;
-    /** Updated by field */
-    updatedBy: string;
-    /** Event type for creation (e.g., 'Post.created') */
-    created: string;
-    /** Event type for update (e.g., 'Post.updated') */
-    updated: string;
-    /** Event type for deletion (e.g., 'Post.deleted') */
-    deleted: string;
-}
 /**
  * Base identifier for all entities (URL-centric)
  */
@@ -409,6 +192,11 @@ export declare function resolveUrl(entity: EntityId): string;
 export declare function resolveShortUrl(entity: Pick<EntityId, 'ns' | 'id'>): string;
 /**
  * Parse a URL into EntityId components
+ *
+ * Supports both full URLs and type/id paths:
+ * - Full URL: 'https://example.com/User/john' -> { ns: 'example.com', type: 'User', id: 'john' }
+ * - Type/ID path: 'User/john' -> { ns: '', type: 'User', id: 'john' }
+ * - Nested path: 'User/org/team/john' -> { ns: '', type: 'User', id: 'org/team/john' }
  */
 export declare function parseUrl(url: string): EntityId;
 /**