@bsb/base 9.0.4 → 9.1.0

package/lib/interfaces/schema-types.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * BSB (Better-Service-Base) is an event-bus based microservice framework.
  * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
@@ -25,557 +24,123 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.bsb = void 0;
-exports.optional = optional;
-exports.nullable = nullable;
-exports.bsbToJsonSchema = bsbToJsonSchema;
-exports.bsbToZod = bsbToZod;
-const zod_1 = require("zod");
-// ============================================================================
-// Builder API - Fluent Interface for Creating BSB Types
-// ============================================================================
-/**
- * BSB type builder providing a fluent API for creating cross-language type definitions.
- *
- * @example
- * ```typescript
- * import { bsb, optional } from '@bsb/base';
- *
- * const UserSchema = bsb.object({
- *   id: bsb.uuid('User unique identifier'),
- *   name: bsb.string({ min: 1, max: 100, description: 'User full name' }),
- *   email: bsb.string({ description: 'User email address' }),
- *   age: optional(bsb.int32({ min: 0, max: 150, description: 'User age' })),
- * });
- * ```
- */
-exports.bsb = {
-    /**
-     * Create a string type with optional constraints.
-     */
+import * as av from '@anyvali/js';
+export function withDescription(schema, description) {
+    if (!description) {
+        return schema;
+    }
+    const originalExport = schema.export.bind(schema);
+    schema.export = ((mode) => {
+        const doc = originalExport(mode);
+        doc.extensions = {
+            ...doc.extensions,
+            bsb: {
+                ...(doc.extensions?.bsb ?? {}),
+                description,
+            },
+        };
+        return doc;
+    });
+    return schema;
+}
+function withNumericOptions(schema, options) {
+    let next = schema;
+    if (options?.min !== undefined)
+        next = next.min(options.min);
+    if (options?.max !== undefined)
+        next = next.max(options.max);
+    return withDescription(next, options?.description);
+}
+export const bsb = {
     string(options) {
-        return {
-            _bsb: 'string',
-            minLength: options?.min,
-            maxLength: options?.max,
-            pattern: options?.pattern,
-            description: options?.description,
-        };
+        let schema = av.string();
+        if (options?.min !== undefined)
+            schema = schema.minLength(options.min);
+        if (options?.max !== undefined)
+            schema = schema.maxLength(options.max);
+        if (options?.pattern)
+            schema = schema.pattern(options.pattern);
+        return withDescription(schema, options?.description);
     },
-    /**
-     * Create a UUID string type (RFC 4122).
-     *
-     * Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: string
-     * - C#: Guid
-     * - Go: uuid.UUID
-     * - Java: UUID
-     */
     uuid(description) {
-        return {
-            _bsb: 'string',
-            format: 'uuid',
-            description,
-        };
+        return withDescription(av.string().format('uuid'), description);
     },
-    /**
-     * Create an ISO 8601 datetime string type.
-     *
-     * Format: 2024-01-01T12:00:00Z
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: Date | string
-     * - C#: DateTime
-     * - Go: time.Time
-     * - Java: Instant
-     */
     datetime(description) {
-        return {
-            _bsb: 'string',
-            format: 'datetime',
-            description,
-        };
+        return withDescription(av.string().format('date-time'), description);
     },
-    /**
-     * Create an email address string type.
-     */
     email(description) {
-        return {
-            _bsb: 'string',
-            format: 'email',
-            description,
-        };
+        return withDescription(av.string().format('email'), description);
     },
-    /**
-     * Create a URI string type.
-     */
     uri(description) {
-        return {
-            _bsb: 'string',
-            format: 'uri',
-            description,
-        };
+        return withDescription(av.string().format('url'), description);
     },
-    /**
-     * Create a URL string type.
-     */
     url(description) {
-        return {
-            _bsb: 'string',
-            format: 'url',
-            description,
-        };
+        return withDescription(av.string().format('url'), description);
     },
-    /**
-     * Create a 32-bit signed integer type.
-     *
-     * Range: -2,147,483,648 to 2,147,483,647
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: number
-     * - C#: int
-     * - Go: int32
-     * - Java: int
-     */
     int32(options) {
-        return {
-            _bsb: 'number',
-            numberType: 'int32',
-            min: options?.min ?? -2147483648,
-            max: options?.max ?? 2147483647,
-            description: options?.description,
-        };
+        return withNumericOptions(av.int32(), options);
     },
-    /**
-     * Create a 64-bit signed integer type.
-     *
-     * Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
-     *
-     * Note: JavaScript can only safely represent integers up to 2^53.
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: number
-     * - C#: long
-     * - Go: int64
-     * - Java: long
-     */
     int64(options) {
-        return {
-            _bsb: 'number',
-            numberType: 'int64',
-            min: options?.min,
-            max: options?.max,
-            description: options?.description,
-        };
+        return withNumericOptions(av.int64(), options);
     },
-    /**
-     * Create a 32-bit floating point number type.
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: number
-     * - C#: float
-     * - Go: float32
-     * - Java: float
-     */
     float(options) {
-        return {
-            _bsb: 'number',
-            numberType: 'float',
-            min: options?.min,
-            max: options?.max,
-            description: options?.description,
-        };
+        return withNumericOptions(av.float32(), options);
     },
-    /**
-     * Create a 64-bit floating point number type.
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: number
-     * - C#: double
-     * - Go: float64
-     * - Java: double
-     */
     double(options) {
-        return {
-            _bsb: 'number',
-            numberType: 'double',
-            min: options?.min,
-            max: options?.max,
-            description: options?.description,
-        };
+        return withNumericOptions(av.float64(), options);
+    },
+    number(options) {
+        return withNumericOptions(av.number(), options);
     },
-    /**
-     * Create a boolean type.
-     *
-     * Language mappings:
-     * - JavaScript/TypeScript: boolean
-     * - C#: bool
-     * - Go: bool
-     * - Java: boolean
-     */
     boolean(description) {
-        return {
-            _bsb: 'boolean',
-            description,
-        };
+        return withDescription(av.bool(), description);
     },
-    /**
-     * Create a bytes type for binary data.
-     * Maps to:
-     * - JavaScript/TypeScript: Uint8Array or Buffer
-     * - C#: byte[]
-     * - Go: []byte
-     * - Java: byte[]
-     * - Python: bytes
-     */
     bytes(description) {
-        return {
-            _bsb: 'bytes',
-            description,
-        };
+        return withDescription(av.unknown(), description);
     },
-    /**
-     * Create an array type with element type and optional size constraints.
-     *
-     * @example
-     * ```typescript
-     * const TagsSchema = bsb.array(
-     *   bsb.string({ max: 50 }),
-     *   { min: 1, max: 10, description: 'List of tags' }
-     * );
-     * ```
-     */
     array(items, options) {
-        return {
-            _bsb: 'array',
-            items,
-            minItems: options?.min,
-            maxItems: options?.max,
-            description: options?.description,
-        };
+        let schema = av.array(items);
+        if (options?.min !== undefined)
+            schema = schema.minItems(options.min);
+        if (options?.max !== undefined)
+            schema = schema.maxItems(options.max);
+        return withDescription(schema, options?.description);
     },
-    /**
-     * Create an object type with named properties.
-     *
-     * Required fields are automatically determined based on the optional flag.
-     *
-     * @example
-     * ```typescript
-     * const UserSchema = bsb.object({
-     *   id: bsb.uuid('User ID'),
-     *   name: bsb.string({ min: 1, max: 100, description: 'Full name' }),
-     *   email: optional(bsb.email('Email address')),
-     * }, 'User object');
-     * ```
-     */
     object(properties, description) {
-        // Compute required fields (non-optional)
-        const required = Object.keys(properties).filter((key) => properties[key].optional !== true);
-        return {
-            _bsb: 'object',
-            properties,
-            required,
-            description,
-        };
+        return withDescription(av.object(properties, { unknownKeys: 'strip' }), description);
     },
-    /**
-     * Create an enum type with fixed string values.
-     *
-     * @example
-     * ```typescript
-     * const StatusSchema = bsb.enum(
-     *   ['pending', 'in-progress', 'completed', 'failed'],
-     *   'Task status'
-     * );
-     * ```
-     */
     enum(values, description) {
-        return {
-            _bsb: 'enum',
-            values: [...values],
-            description,
-        };
+        return withDescription(av.enum_(values), description);
     },
-    /**
-     * Create a union type representing one of multiple possible types.
-     *
-     * @example
-     * ```typescript
-     * const IdSchema = bsb.union([
-     *   bsb.uuid('UUID identifier'),
-     *   bsb.int32({ description: 'Numeric identifier' }),
-     * ], 'Flexible identifier');
-     * ```
-     */
     union(types, description) {
-        return {
-            _bsb: 'union',
-            types,
-            description,
-        };
-    },
-    /**
-     * Create a generic number type (defaults to double for floating point).
-     * This is a convenience wrapper for double().
-     */
-    number(options) {
-        return this.double(options);
+        if (types.length === 0) {
+            return withDescription(av.unknown(), description ?? 'unknown');
+        }
+        return withDescription(av.union(types), description);
     },
-    /**
-     * Create a void type for functions that don't return a value.
-     */
     void() {
-        return this.union([], 'void');
+        return withDescription(av.unknown(), 'void');
     },
-    /**
-     * Create an unknown type for dynamic/any data.
-     */
     unknown(description) {
-        return this.union([], description || 'unknown');
+        return withDescription(av.unknown(), description);
     },
-    /**
-     * Create a record/map type with string keys and a value type.
-     */
-    record(keyType, valueType, description) {
-        // Records are represented as objects with dynamic properties
-        // For now, we'll use a union as a placeholder
-        return this.union([valueType], description || 'record');
+    record(_keyType, valueType, description) {
+        return withDescription(av.record(valueType), description);
     },
 };
-// ============================================================================
-// Type Modifiers
-// ============================================================================
-/**
- * Mark a type as optional.
- * Optional fields are not required in object schemas.
- *
- * @example
- * ```typescript
- * const UserSchema = bsb.object({
- *   name: bsb.string(),           // Required
- *   bio: optional(bsb.string()),  // Optional
- * });
- * ```
- */
-function optional(type) {
-    return { ...type, optional: true };
+export function optional(type) {
+    return av.optional(type);
 }
-/**
- * Mark a type as nullable.
- * Nullable fields can have null values in addition to their defined type.
- *
- * @example
- * ```typescript
- * const UserSchema = bsb.object({
- *   lastLogin: nullable(bsb.datetime('Last login time')),
- * });
- * ```
- */
-function nullable(type) {
-    return { ...type, nullable: true };
+export function nullable(type) {
+    return av.nullable(type);
 }
-// ============================================================================
-// JSON Schema Conversion
-// ============================================================================
-/**
- * Convert BSB type to JSON Schema format.
- * Used for schema export and client code generation.
- */
-function bsbToJsonSchema(type) {
-    const base = {};
-    if (type.description)
-        base.description = type.description;
-    switch (type._bsb) {
-        case 'string': {
-            const schema = { ...base, type: 'string' };
-            if (type.format)
-                schema.format = type.format;
-            if (type.minLength !== undefined)
-                schema.minLength = type.minLength;
-            if (type.maxLength !== undefined)
-                schema.maxLength = type.maxLength;
-            if (type.pattern)
-                schema.pattern = type.pattern;
-            return schema;
-        }
-        case 'number': {
-            const isInteger = type.numberType === 'int32' || type.numberType === 'int64';
-            const schema = {
-                ...base,
-                type: isInteger ? 'integer' : 'number',
-                format: type.numberType,
-            };
-            if (type.min !== undefined)
-                schema.minimum = type.min;
-            if (type.max !== undefined)
-                schema.maximum = type.max;
-            return schema;
-        }
-        case 'boolean':
-            return { ...base, type: 'boolean' };
-        case 'bytes':
-            return {
-                ...base,
-                type: 'string',
-                contentEncoding: 'base64',
-            };
-        case 'array': {
-            const schema = {
-                ...base,
-                type: 'array',
-                items: bsbToJsonSchema(type.items),
-            };
-            if (type.minItems !== undefined)
-                schema.minItems = type.minItems;
-            if (type.maxItems !== undefined)
-                schema.maxItems = type.maxItems;
-            return schema;
-        }
-        case 'object': {
-            const properties = {};
-            for (const [key, value] of Object.entries(type.properties)) {
-                properties[key] = bsbToJsonSchema(value);
-            }
-            return {
-                ...base,
-                type: 'object',
-                properties,
-                required: type.required,
-            };
-        }
-        case 'enum':
-            return {
-                ...base,
-                type: 'string',
-                enum: type.values,
-            };
-        case 'union':
-            return {
-                ...base,
-                oneOf: type.types.map(bsbToJsonSchema),
-            };
-        default:
-            throw new Error(`Unknown BSB type: ${type._bsb}`);
-    }
+export function bsbToJsonSchema(type) {
+    return type.export('extended');
 }
-// ============================================================================
-// Runtime Validation (Zod Conversion)
-// ============================================================================
-/**
- * Convert BSB type to Zod schema for runtime validation.
- * This is only used in Node.js plugins for runtime validation.
- * Other languages will have their own validation implementations.
- */
-function bsbToZod(type) {
-    switch (type._bsb) {
-        case 'string': {
-            let schema = zod_1.z.string();
-            if (type.format === 'uuid')
-                schema = schema.uuid();
-            if (type.format === 'datetime')
-                schema = schema.datetime();
-            if (type.format === 'email')
-                schema = schema.email();
-            if (type.format === 'uri' || type.format === 'url')
-                schema = schema.url();
-            if (type.minLength !== undefined)
-                schema = schema.min(type.minLength);
-            if (type.maxLength !== undefined)
-                schema = schema.max(type.maxLength);
-            if (type.pattern)
-                schema = schema.regex(new RegExp(type.pattern));
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'number': {
-            let schema = zod_1.z.number();
-            if (type.numberType === 'int32' || type.numberType === 'int64') {
-                schema = schema.int();
-            }
-            if (type.min !== undefined)
-                schema = schema.min(type.min);
-            if (type.max !== undefined)
-                schema = schema.max(type.max);
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'boolean': {
-            let schema = zod_1.z.boolean();
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'bytes': {
-            let schema = zod_1.z.instanceof(Uint8Array);
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'array': {
-            let schema = zod_1.z.array(bsbToZod(type.items));
-            if (type.minItems !== undefined)
-                schema = schema.min(type.minItems);
-            if (type.maxItems !== undefined)
-                schema = schema.max(type.maxItems);
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'object': {
-            const shape = {};
-            for (const [key, value] of Object.entries(type.properties)) {
-                shape[key] = bsbToZod(value);
-            }
-            let schema = zod_1.z.object(shape);
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'enum': {
-            let schema = zod_1.z.enum(type.values);
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        case 'union': {
-            // Empty union = unknown/any type (used by bsb.unknown() and bsb.void())
-            if (type.types.length === 0) {
-                let schema = zod_1.z.unknown();
-                if (type.optional)
-                    return schema.optional();
-                if (type.nullable)
-                    return schema.nullable();
-                return schema;
-            }
-            const schemas = type.types.map(bsbToZod);
-            let schema = zod_1.z.union(schemas);
-            if (type.optional)
-                return schema.optional();
-            if (type.nullable)
-                return schema.nullable();
-            return schema;
-        }
-        default:
-            throw new Error(`Unknown BSB type: ${type._bsb}`);
-    }
+export function exportPortableSchema(type) {
+    return type.export('extended');
+}
+export function importPortableSchema(document) {
+    return av.importSchema(document);
 }
 //# sourceMappingURL=schema-types.js.map