digital-objects 1.0.0

package/dist/schema-validation.js

@@ -0,0 +1,233 @@
+/**
+ * Runtime schema validation for Digital Objects
+ *
+ * Validates Thing data against Noun schemas when validation is enabled.
+ * Provides clear, actionable error messages with field paths and suggestions.
+ */
+/**
+ * Type guard to check if a field definition is an extended definition (object with type)
+ */
+function isExtendedFieldDefinition(def) {
+    return typeof def === 'object' && def !== null && 'type' in def;
+}
+/**
+ * Get the actual JavaScript type of a value for validation purposes
+ */
+function getActualType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (value instanceof Date)
+        return 'date';
+    return typeof value;
+}
+/**
+ * Get a suggestion for fixing a type mismatch error
+ */
+function getSuggestion(expected, actual, value) {
+    // String to number
+    if (expected === 'number' && actual === 'string') {
+        const num = Number(value);
+        if (!isNaN(num)) {
+            return `Convert to number: ${num}`;
+        }
+        return 'Provide a valid number';
+    }
+    // Number to string
+    if (expected === 'string' && actual === 'number') {
+        return `Convert to string: "${value}"`;
+    }
+    // String to boolean
+    if (expected === 'boolean' && actual === 'string') {
+        const str = String(value).toLowerCase();
+        if (str === 'true' || str === 'false') {
+            return `Convert to boolean: ${str === 'true'}`;
+        }
+        return 'Use true or false';
+    }
+    // Array expected
+    if (expected === 'array' && actual !== 'array') {
+        return 'Wrap value in an array: [value]';
+    }
+    // Object expected
+    if (expected === 'object' && actual !== 'object') {
+        return 'Provide an object: { ... }';
+    }
+    // Date/datetime (expected string-based type but got wrong type)
+    if ((expected === 'date' || expected === 'datetime') && actual !== 'string') {
+        return 'Provide a valid ISO 8601 date string';
+    }
+    // URL (expected string-based type but got wrong type)
+    if (expected === 'url' && actual !== 'string') {
+        return 'Provide a valid URL starting with http:// or https://';
+    }
+    // Markdown
+    if (expected === 'markdown' && actual !== 'string') {
+        return 'Provide a string containing markdown content';
+    }
+    return undefined;
+}
+/**
+ * Create a validation error with consistent formatting
+ */
+function createError(field, code, expected, received, value) {
+    let message;
+    switch (code) {
+        case 'REQUIRED_FIELD':
+            message = `Missing required field '${field}'`;
+            break;
+        case 'TYPE_MISMATCH':
+            message = `Field '${field}' has wrong type: expected ${expected}, got ${received}`;
+            break;
+        case 'INVALID_FORMAT':
+            message = `Field '${field}' has invalid format: expected ${expected}`;
+            break;
+        case 'UNKNOWN_FIELD':
+            message = `Unknown field '${field}'`;
+            break;
+    }
+    const error = {
+        field,
+        message,
+        expected,
+        received,
+        code,
+    };
+    // Add suggestion if available
+    const suggestion = getSuggestion(expected, received, value);
+    if (suggestion) {
+        error.suggestion = suggestion;
+    }
+    return error;
+}
+/**
+ * Internal validation logic that collects errors
+ *
+ * @param data - The data to validate
+ * @param schema - The schema to validate against
+ * @param path - Current field path for nested objects
+ * @returns Array of validation errors
+ */
+function collectErrors(data, schema, path = '') {
+    const errors = [];
+    for (const [field, def] of Object.entries(schema)) {
+        const fieldPath = path ? `${path}.${field}` : field;
+        const value = data[field];
+        // Handle extended field definitions (object with type and required)
+        if (isExtendedFieldDefinition(def)) {
+            // Check required fields
+            if (def.required && (value === undefined || value === null)) {
+                errors.push(createError(fieldPath, 'REQUIRED_FIELD', def.type, value === null ? 'null' : 'undefined', value));
+                continue;
+            }
+            // Skip validation if field is not present and not required
+            if (value === undefined)
+                continue;
+            // Type validation
+            const actualType = getActualType(value);
+            // Special handling for string-based types that should validate as strings
+            const stringBasedTypes = ['date', 'datetime', 'url', 'markdown', 'json'];
+            const normalizedExpected = stringBasedTypes.includes(def.type) ? 'string' : def.type;
+            if (normalizedExpected !== actualType) {
+                errors.push(createError(fieldPath, 'TYPE_MISMATCH', def.type, actualType, value));
+            }
+        }
+        else {
+            // Simple field type (string like 'string', 'number', etc.)
+            // These are not required by default and just validate type if present
+            if (value === undefined)
+                continue;
+            const actualType = getActualType(value);
+            const expectedType = def.replace('?', ''); // Remove optional marker
+            // Skip relation types (contain '.')
+            if (expectedType.includes('.'))
+                continue;
+            // Skip bracket-wrapped relation types
+            if (expectedType.startsWith('[') && expectedType.endsWith(']'))
+                continue;
+            // Special handling for string-based types that should validate as strings
+            const stringBasedTypes = ['date', 'datetime', 'url', 'markdown', 'json'];
+            const normalizedExpected = stringBasedTypes.includes(expectedType) ? 'string' : expectedType;
+            if (normalizedExpected !== actualType) {
+                errors.push(createError(fieldPath, 'TYPE_MISMATCH', expectedType, actualType, value));
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Format validation errors for display in error messages
+ */
+function formatErrors(errors) {
+    if (errors.length === 0)
+        return '';
+    const lines = errors.map((e) => {
+        let line = `  - ${e.message}`;
+        if (e.suggestion) {
+            line += ` (${e.suggestion})`;
+        }
+        return line;
+    });
+    return lines.join('\n');
+}
+/**
+ * Validates data against a schema definition without throwing
+ *
+ * Use this for pre-flight validation to check if data is valid
+ * before attempting create/update operations.
+ *
+ * @param data - The data to validate
+ * @param schema - The schema to validate against (from Noun.schema)
+ * @returns ValidationResult with valid boolean and errors array
+ *
+ * @example
+ * ```typescript
+ * const result = validateOnly(userData, userSchema)
+ * if (!result.valid) {
+ *   console.log('Validation errors:', result.errors)
+ *   // Handle errors gracefully
+ * }
+ * ```
+ */
+export function validateOnly(data, schema) {
+    if (!schema) {
+        return { valid: true, errors: [] };
+    }
+    const errors = collectErrors(data, schema);
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Validates data against a schema definition
+ *
+ * @param data - The data to validate
+ * @param schema - The schema to validate against (from Noun.schema)
+ * @param options - Validation options (validate: true to enable)
+ * @throws Error if validation fails with detailed error messages
+ *
+ * @example
+ * ```typescript
+ * // Enable validation with options
+ * await provider.create('User', userData, undefined, { validate: true })
+ *
+ * // Error message example:
+ * // Validation failed (2 errors):
+ * //   - Missing required field 'email'
+ * //   - Field 'age' has wrong type: expected number, got string (Convert to number: 25)
+ * ```
+ */
+export function validateData(data, schema, options) {
+    // Skip validation if not enabled or no schema
+    if (!options?.validate || !schema)
+        return;
+    const errors = collectErrors(data, schema);
+    if (errors.length > 0) {
+        const errorCount = errors.length === 1 ? '1 error' : `${errors.length} errors`;
+        const formatted = formatErrors(errors);
+        throw new Error(`Validation failed (${errorCount}):\n${formatted}`);
+    }
+}
+//# sourceMappingURL=schema-validation.js.map

package/dist/schema-validation.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Core types for Digital Objects
+ *
+ * A unified nouns/verbs/things/actions model that provides:
+ * - Linguistic consistency (singular/plural, conjugations)
+ * - Entity definitions (Nouns) and instances (Things)
+ * - Action definitions (Verbs) and instances (Actions)
+ * - Graph relationships through Actions
+ * - Event sourcing and audit trails
+ */
+/**
+ * Query limit constants to prevent memory exhaustion
+ */
+export declare const DEFAULT_LIMIT = 100;
+export declare const MAX_LIMIT = 1000;
+/**
+ * Direction for graph traversal
+ */
+export type Direction = 'in' | 'out' | 'both';
+/**
+ * Validates direction parameter for graph traversal methods.
+ * @throws Error if direction is not 'in', 'out', or 'both'
+ */
+export declare function validateDirection(direction: string): Direction;
+/**
+ * Noun - Entity type definition with linguistic forms
+ */
+export interface Noun {
+    name: string;
+    singular: string;
+    plural: string;
+    slug: string;
+    description?: string;
+    schema?: Record<string, FieldDefinition>;
+    createdAt: Date;
+}
+export interface NounDefinition {
+    name: string;
+    singular?: string;
+    plural?: string;
+    description?: string;
+    schema?: Record<string, FieldDefinition>;
+}
+/**
+ * Verb - Action definition with all conjugations
+ */
+export interface Verb {
+    name: string;
+    action: string;
+    act: string;
+    activity: string;
+    event: string;
+    reverseBy?: string;
+    reverseAt?: string;
+    reverseIn?: string;
+    inverse?: string;
+    description?: string;
+    createdAt: Date;
+}
+export interface VerbDefinition {
+    name: string;
+    action?: string;
+    act?: string;
+    activity?: string;
+    event?: string;
+    reverseBy?: string;
+    reverseAt?: string;
+    reverseIn?: string;
+    inverse?: string;
+    description?: string;
+}
+/**
+ * Thing - Entity instance
+ */
+export interface Thing<T = Record<string, unknown>> {
+    id: string;
+    noun: string;
+    data: T;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Action - Events + Relationships + Audit Trail (unified!)
+ *
+ * An action represents:
+ * - A graph edge (subject --verb--> object)
+ * - An event (something happened)
+ * - An audit record (who did what when)
+ */
+export interface Action<T = Record<string, unknown>> {
+    id: string;
+    verb: string;
+    subject?: string;
+    object?: string;
+    data?: T;
+    status: ActionStatus;
+    createdAt: Date;
+    completedAt?: Date;
+}
+export type ActionStatus = 'pending' | 'active' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Field definition for schemas
+ *
+ * Can be either a simple type string or an extended definition with options
+ */
+export type FieldDefinition = SimpleFieldType | ExtendedFieldDefinition;
+/**
+ * Simple field type - just a type string
+ */
+export type SimpleFieldType = PrimitiveType | `${string}.${string}` | `[${string}.${string}]` | `${PrimitiveType}?`;
+/**
+ * Extended field definition with options like required, default, etc.
+ */
+export interface ExtendedFieldDefinition {
+    type: PrimitiveType | 'object' | 'array';
+    required?: boolean;
+    default?: unknown;
+}
+export type PrimitiveType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json' | 'markdown' | 'url';
+/**
+ * Validation options for create/update operations
+ */
+export interface ValidationOptions {
+    validate?: boolean;
+}
+/**
+ * List options for queries
+ */
+export interface ListOptions {
+    limit?: number;
+    offset?: number;
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
+}
+/**
+ * Action query options
+ */
+export interface ActionOptions extends ListOptions {
+    verb?: string;
+    subject?: string;
+    object?: string;
+    status?: ActionStatus | ActionStatus[];
+}
+/**
+ * DigitalObjectsProvider - Core storage interface
+ *
+ * Implementations: MemoryProvider, NS (DurableObject)
+ */
+export interface DigitalObjectsProvider {
+    defineNoun(def: NounDefinition): Promise<Noun>;
+    getNoun(name: string): Promise<Noun | null>;
+    listNouns(): Promise<Noun[]>;
+    defineVerb(def: VerbDefinition): Promise<Verb>;
+    getVerb(name: string): Promise<Verb | null>;
+    listVerbs(): Promise<Verb[]>;
+    create<T>(noun: string, data: T, id?: string, options?: ValidationOptions): Promise<Thing<T>>;
+    get<T>(id: string): Promise<Thing<T> | null>;
+    list<T>(noun: string, options?: ListOptions): Promise<Thing<T>[]>;
+    find<T>(noun: string, where: Partial<T>): Promise<Thing<T>[]>;
+    update<T>(id: string, data: Partial<T>, options?: ValidationOptions): Promise<Thing<T>>;
+    delete(id: string): Promise<boolean>;
+    search<T>(query: string, options?: ListOptions): Promise<Thing<T>[]>;
+    perform<T>(verb: string, subject?: string, object?: string, data?: T): Promise<Action<T>>;
+    getAction<T>(id: string): Promise<Action<T> | null>;
+    listActions<T>(options?: ActionOptions): Promise<Action<T>[]>;
+    deleteAction(id: string): Promise<boolean>;
+    related<T>(id: string, verb?: string, direction?: Direction, options?: ListOptions): Promise<Thing<T>[]>;
+    edges<T>(id: string, verb?: string, direction?: Direction, options?: ListOptions): Promise<Action<T>[]>;
+    createMany<T>(noun: string, items: T[]): Promise<Thing<T>[]>;
+    updateMany<T>(updates: Array<{
+        id: string;
+        data: Partial<T>;
+    }>): Promise<Thing<T>[]>;
+    deleteMany(ids: string[]): Promise<boolean[]>;
+    performMany<T>(actions: Array<{
+        verb: string;
+        subject?: string;
+        object?: string;
+        data?: T;
+    }>): Promise<Action<T>[]>;
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,26 @@
+/**
+ * Core types for Digital Objects
+ *
+ * A unified nouns/verbs/things/actions model that provides:
+ * - Linguistic consistency (singular/plural, conjugations)
+ * - Entity definitions (Nouns) and instances (Things)
+ * - Action definitions (Verbs) and instances (Actions)
+ * - Graph relationships through Actions
+ * - Event sourcing and audit trails
+ */
+/**
+ * Query limit constants to prevent memory exhaustion
+ */
+export const DEFAULT_LIMIT = 100;
+export const MAX_LIMIT = 1000;
+/**
+ * Validates direction parameter for graph traversal methods.
+ * @throws Error if direction is not 'in', 'out', or 'both'
+ */
+export function validateDirection(direction) {
+    if (direction !== 'in' && direction !== 'out' && direction !== 'both') {
+        throw new Error(`Invalid direction: "${direction}". Must be "in", "out", or "both".`);
+    }
+    return direction;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAChC,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAA;AAO7B;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,KAAK,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,uBAAuB,SAAS,oCAAoC,CAAC,CAAA;IACvF,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "digital-objects",
+  "version": "1.0.0",
+  "description": "Unified storage primitive for AI primitives - nouns, verbs, things, actions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./ns": {
+      "import": "./dist/ns-exports.js",
+      "types": "./dist/ns-exports.d.ts"
+    }
+  },
+  "keywords": [
+    "digital-objects",
+    "durable-objects",
+    "cloudflare",
+    "sqlite",
+    "graph",
+    "entity",
+    "nouns",
+    "verbs",
+    "things",
+    "actions",
+    "linguistics"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@org.ai/types": "2.1.3",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20240925.0",
+    "wrangler": "^3.79.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "vitest": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  }
+}