opik 0.0.1

package/src/opik/rest_api/core/schemas/builders/object/object.ts

@@ -0,0 +1,324 @@
+import { MaybeValid, Schema, SchemaType, ValidationError } from "../../Schema";
+import { entries } from "../../utils/entries";
+import { filterObject } from "../../utils/filterObject";
+import { getErrorMessageForIncorrectType } from "../../utils/getErrorMessageForIncorrectType";
+import { isPlainObject } from "../../utils/isPlainObject";
+import { keys } from "../../utils/keys";
+import { maybeSkipValidation } from "../../utils/maybeSkipValidation";
+import { partition } from "../../utils/partition";
+import { getObjectLikeUtils } from "../object-like";
+import { getSchemaUtils } from "../schema-utils";
+import { isProperty } from "./property";
+import {
+    BaseObjectSchema,
+    inferObjectSchemaFromPropertySchemas,
+    inferParsedObjectFromPropertySchemas,
+    inferRawObjectFromPropertySchemas,
+    ObjectSchema,
+    ObjectUtils,
+    PropertySchemas,
+} from "./types";
+
+interface ObjectPropertyWithRawKey {
+    rawKey: string;
+    parsedKey: string;
+    valueSchema: Schema<any, any>;
+}
+
+export function object<ParsedKeys extends string, T extends PropertySchemas<ParsedKeys>>(
+    schemas: T
+): inferObjectSchemaFromPropertySchemas<T> {
+    const baseSchema: BaseObjectSchema<
+        inferRawObjectFromPropertySchemas<T>,
+        inferParsedObjectFromPropertySchemas<T>
+    > = {
+        _getRawProperties: () =>
+            Object.entries(schemas).map(([parsedKey, propertySchema]) =>
+                isProperty(propertySchema) ? propertySchema.rawKey : parsedKey
+            ) as unknown as (keyof inferRawObjectFromPropertySchemas<T>)[],
+        _getParsedProperties: () => keys(schemas) as unknown as (keyof inferParsedObjectFromPropertySchemas<T>)[],
+
+        parse: (raw, opts) => {
+            const rawKeyToProperty: Record<string, ObjectPropertyWithRawKey> = {};
+            const requiredKeys: string[] = [];
+
+            for (const [parsedKey, schemaOrObjectProperty] of entries(schemas)) {
+                const rawKey = isProperty(schemaOrObjectProperty) ? schemaOrObjectProperty.rawKey : parsedKey;
+                const valueSchema: Schema<any, any> = isProperty(schemaOrObjectProperty)
+                    ? schemaOrObjectProperty.valueSchema
+                    : schemaOrObjectProperty;
+
+                const property: ObjectPropertyWithRawKey = {
+                    rawKey,
+                    parsedKey: parsedKey as string,
+                    valueSchema,
+                };
+
+                rawKeyToProperty[rawKey] = property;
+
+                if (isSchemaRequired(valueSchema)) {
+                    requiredKeys.push(rawKey);
+                }
+            }
+
+            return validateAndTransformObject({
+                value: raw,
+                requiredKeys,
+                getProperty: (rawKey) => {
+                    const property = rawKeyToProperty[rawKey];
+                    if (property == null) {
+                        return undefined;
+                    }
+                    return {
+                        transformedKey: property.parsedKey,
+                        transform: (propertyValue) =>
+                            property.valueSchema.parse(propertyValue, {
+                                ...opts,
+                                breadcrumbsPrefix: [...(opts?.breadcrumbsPrefix ?? []), rawKey],
+                            }),
+                    };
+                },
+                unrecognizedObjectKeys: opts?.unrecognizedObjectKeys,
+                skipValidation: opts?.skipValidation,
+                breadcrumbsPrefix: opts?.breadcrumbsPrefix,
+                omitUndefined: opts?.omitUndefined,
+            });
+        },
+
+        json: (parsed, opts) => {
+            const requiredKeys: string[] = [];
+
+            for (const [parsedKey, schemaOrObjectProperty] of entries(schemas)) {
+                const valueSchema: Schema<any, any> = isProperty(schemaOrObjectProperty)
+                    ? schemaOrObjectProperty.valueSchema
+                    : schemaOrObjectProperty;
+
+                if (isSchemaRequired(valueSchema)) {
+                    requiredKeys.push(parsedKey as string);
+                }
+            }
+
+            return validateAndTransformObject({
+                value: parsed,
+                requiredKeys,
+                getProperty: (
+                    parsedKey
+                ): { transformedKey: string; transform: (propertyValue: unknown) => MaybeValid<any> } | undefined => {
+                    const property = schemas[parsedKey as keyof T];
+
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                    if (property == null) {
+                        return undefined;
+                    }
+
+                    if (isProperty(property)) {
+                        return {
+                            transformedKey: property.rawKey,
+                            transform: (propertyValue) =>
+                                property.valueSchema.json(propertyValue, {
+                                    ...opts,
+                                    breadcrumbsPrefix: [...(opts?.breadcrumbsPrefix ?? []), parsedKey],
+                                }),
+                        };
+                    } else {
+                        return {
+                            transformedKey: parsedKey,
+                            transform: (propertyValue) =>
+                                property.json(propertyValue, {
+                                    ...opts,
+                                    breadcrumbsPrefix: [...(opts?.breadcrumbsPrefix ?? []), parsedKey],
+                                }),
+                        };
+                    }
+                },
+                unrecognizedObjectKeys: opts?.unrecognizedObjectKeys,
+                skipValidation: opts?.skipValidation,
+                breadcrumbsPrefix: opts?.breadcrumbsPrefix,
+                omitUndefined: opts?.omitUndefined,
+            });
+        },
+
+        getType: () => SchemaType.OBJECT,
+    };
+
+    return {
+        ...maybeSkipValidation(baseSchema),
+        ...getSchemaUtils(baseSchema),
+        ...getObjectLikeUtils(baseSchema),
+        ...getObjectUtils(baseSchema),
+    };
+}
+
+function validateAndTransformObject<Transformed>({
+    value,
+    requiredKeys,
+    getProperty,
+    unrecognizedObjectKeys = "fail",
+    skipValidation = false,
+    breadcrumbsPrefix = [],
+}: {
+    value: unknown;
+    requiredKeys: string[];
+    getProperty: (
+        preTransformedKey: string
+    ) => { transformedKey: string; transform: (propertyValue: unknown) => MaybeValid<any> } | undefined;
+    unrecognizedObjectKeys: "fail" | "passthrough" | "strip" | undefined;
+    skipValidation: boolean | undefined;
+    breadcrumbsPrefix: string[] | undefined;
+    omitUndefined: boolean | undefined;
+}): MaybeValid<Transformed> {
+    if (!isPlainObject(value)) {
+        return {
+            ok: false,
+            errors: [
+                {
+                    path: breadcrumbsPrefix,
+                    message: getErrorMessageForIncorrectType(value, "object"),
+                },
+            ],
+        };
+    }
+
+    const missingRequiredKeys = new Set(requiredKeys);
+    const errors: ValidationError[] = [];
+    const transformed: Record<string | number | symbol, any> = {};
+
+    for (const [preTransformedKey, preTransformedItemValue] of Object.entries(value)) {
+        const property = getProperty(preTransformedKey);
+
+        if (property != null) {
+            missingRequiredKeys.delete(preTransformedKey);
+
+            const value = property.transform(preTransformedItemValue);
+            if (value.ok) {
+                transformed[property.transformedKey] = value.value;
+            } else {
+                transformed[preTransformedKey] = preTransformedItemValue;
+                errors.push(...value.errors);
+            }
+        } else {
+            switch (unrecognizedObjectKeys) {
+                case "fail":
+                    errors.push({
+                        path: [...breadcrumbsPrefix, preTransformedKey],
+                        message: `Unexpected key "${preTransformedKey}"`,
+                    });
+                    break;
+                case "strip":
+                    break;
+                case "passthrough":
+                    transformed[preTransformedKey] = preTransformedItemValue;
+                    break;
+            }
+        }
+    }
+
+    errors.push(
+        ...requiredKeys
+            .filter((key) => missingRequiredKeys.has(key))
+            .map((key) => ({
+                path: breadcrumbsPrefix,
+                message: `Missing required key "${key}"`,
+            }))
+    );
+
+    if (errors.length === 0 || skipValidation) {
+        return {
+            ok: true,
+            value: transformed as Transformed,
+        };
+    } else {
+        return {
+            ok: false,
+            errors,
+        };
+    }
+}
+
+export function getObjectUtils<Raw, Parsed>(schema: BaseObjectSchema<Raw, Parsed>): ObjectUtils<Raw, Parsed> {
+    return {
+        extend: <RawExtension, ParsedExtension>(extension: ObjectSchema<RawExtension, ParsedExtension>) => {
+            const baseSchema: BaseObjectSchema<Raw & RawExtension, Parsed & ParsedExtension> = {
+                _getParsedProperties: () => [...schema._getParsedProperties(), ...extension._getParsedProperties()],
+                _getRawProperties: () => [...schema._getRawProperties(), ...extension._getRawProperties()],
+                parse: (raw, opts) => {
+                    return validateAndTransformExtendedObject({
+                        extensionKeys: extension._getRawProperties(),
+                        value: raw,
+                        transformBase: (rawBase) => schema.parse(rawBase, opts),
+                        transformExtension: (rawExtension) => extension.parse(rawExtension, opts),
+                    });
+                },
+                json: (parsed, opts) => {
+                    return validateAndTransformExtendedObject({
+                        extensionKeys: extension._getParsedProperties(),
+                        value: parsed,
+                        transformBase: (parsedBase) => schema.json(parsedBase, opts),
+                        transformExtension: (parsedExtension) => extension.json(parsedExtension, opts),
+                    });
+                },
+                getType: () => SchemaType.OBJECT,
+            };
+
+            return {
+                ...baseSchema,
+                ...getSchemaUtils(baseSchema),
+                ...getObjectLikeUtils(baseSchema),
+                ...getObjectUtils(baseSchema),
+            };
+        },
+    };
+}
+
+function validateAndTransformExtendedObject<PreTransformedExtension, TransformedBase, TransformedExtension>({
+    extensionKeys,
+    value,
+    transformBase,
+    transformExtension,
+}: {
+    extensionKeys: (keyof PreTransformedExtension)[];
+    value: unknown;
+    transformBase: (value: unknown) => MaybeValid<TransformedBase>;
+    transformExtension: (value: unknown) => MaybeValid<TransformedExtension>;
+}): MaybeValid<TransformedBase & TransformedExtension> {
+    const extensionPropertiesSet = new Set(extensionKeys);
+    const [extensionProperties, baseProperties] = partition(keys(value), (key) =>
+        extensionPropertiesSet.has(key as keyof PreTransformedExtension)
+    );
+
+    const transformedBase = transformBase(filterObject(value, baseProperties));
+    const transformedExtension = transformExtension(filterObject(value, extensionProperties));
+
+    if (transformedBase.ok && transformedExtension.ok) {
+        return {
+            ok: true,
+            value: {
+                ...transformedBase.value,
+                ...transformedExtension.value,
+            },
+        };
+    } else {
+        return {
+            ok: false,
+            errors: [
+                ...(transformedBase.ok ? [] : transformedBase.errors),
+                ...(transformedExtension.ok ? [] : transformedExtension.errors),
+            ],
+        };
+    }
+}
+
+function isSchemaRequired(schema: Schema<any, any>): boolean {
+    return !isSchemaOptional(schema);
+}
+
+function isSchemaOptional(schema: Schema<any, any>): boolean {
+    switch (schema.getType()) {
+        case SchemaType.ANY:
+        case SchemaType.UNKNOWN:
+        case SchemaType.OPTIONAL:
+            return true;
+        default:
+            return false;
+    }
+}

package/src/opik/rest_api/core/schemas/builders/object/objectWithoutOptionalProperties.ts

@@ -0,0 +1,18 @@
+import { object } from "./object";
+import { inferParsedPropertySchema, inferRawObjectFromPropertySchemas, ObjectSchema, PropertySchemas } from "./types";
+
+export function objectWithoutOptionalProperties<ParsedKeys extends string, T extends PropertySchemas<ParsedKeys>>(
+    schemas: T
+): inferObjectWithoutOptionalPropertiesSchemaFromPropertySchemas<T> {
+    return object(schemas) as unknown as inferObjectWithoutOptionalPropertiesSchemaFromPropertySchemas<T>;
+}
+
+export type inferObjectWithoutOptionalPropertiesSchemaFromPropertySchemas<T extends PropertySchemas<keyof T>> =
+    ObjectSchema<
+        inferRawObjectFromPropertySchemas<T>,
+        inferParsedObjectWithoutOptionalPropertiesFromPropertySchemas<T>
+    >;
+
+export type inferParsedObjectWithoutOptionalPropertiesFromPropertySchemas<T extends PropertySchemas<keyof T>> = {
+    [K in keyof T]: inferParsedPropertySchema<T[K]>;
+};

package/src/opik/rest_api/core/schemas/builders/object/property.ts

@@ -0,0 +1,23 @@
+import { Schema } from "../../Schema";
+
+export function property<RawKey extends string, RawValue, ParsedValue>(
+    rawKey: RawKey,
+    valueSchema: Schema<RawValue, ParsedValue>
+): Property<RawKey, RawValue, ParsedValue> {
+    return {
+        rawKey,
+        valueSchema,
+        isProperty: true,
+    };
+}
+
+export interface Property<RawKey extends string, RawValue, ParsedValue> {
+    rawKey: RawKey;
+    valueSchema: Schema<RawValue, ParsedValue>;
+    isProperty: true;
+}
+
+export function isProperty<O extends Property<any, any, any>>(maybeProperty: unknown): maybeProperty is O {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return (maybeProperty as O).isProperty;
+}

package/src/opik/rest_api/core/schemas/builders/object/types.ts

@@ -0,0 +1,72 @@
+import { BaseSchema, inferParsed, inferRaw, Schema } from "../../Schema";
+import { addQuestionMarksToNullableProperties } from "../../utils/addQuestionMarksToNullableProperties";
+import { ObjectLikeUtils } from "../object-like";
+import { SchemaUtils } from "../schema-utils";
+import { Property } from "./property";
+
+export type ObjectSchema<Raw, Parsed> = BaseObjectSchema<Raw, Parsed> &
+    ObjectLikeUtils<Raw, Parsed> &
+    ObjectUtils<Raw, Parsed> &
+    SchemaUtils<Raw, Parsed>;
+
+export interface BaseObjectSchema<Raw, Parsed> extends BaseSchema<Raw, Parsed> {
+    _getRawProperties: () => (keyof Raw)[];
+    _getParsedProperties: () => (keyof Parsed)[];
+}
+
+export interface ObjectUtils<Raw, Parsed> {
+    extend: <RawExtension, ParsedExtension>(
+        schemas: ObjectSchema<RawExtension, ParsedExtension>
+    ) => ObjectSchema<Raw & RawExtension, Parsed & ParsedExtension>;
+}
+
+export type inferRawObject<O extends ObjectSchema<any, any>> = O extends ObjectSchema<infer Raw, any> ? Raw : never;
+
+export type inferParsedObject<O extends ObjectSchema<any, any>> = O extends ObjectSchema<any, infer Parsed>
+    ? Parsed
+    : never;
+
+export type inferObjectSchemaFromPropertySchemas<T extends PropertySchemas<keyof T>> = ObjectSchema<
+    inferRawObjectFromPropertySchemas<T>,
+    inferParsedObjectFromPropertySchemas<T>
+>;
+
+export type inferRawObjectFromPropertySchemas<T extends PropertySchemas<keyof T>> =
+    addQuestionMarksToNullableProperties<{
+        [ParsedKey in keyof T as inferRawKey<ParsedKey, T[ParsedKey]>]: inferRawPropertySchema<T[ParsedKey]>;
+    }>;
+
+export type inferParsedObjectFromPropertySchemas<T extends PropertySchemas<keyof T>> =
+    addQuestionMarksToNullableProperties<{
+        [K in keyof T]: inferParsedPropertySchema<T[K]>;
+    }>;
+
+export type PropertySchemas<ParsedKeys extends string | number | symbol> = Record<
+    ParsedKeys,
+    Property<any, any, any> | Schema<any, any>
+>;
+
+export type inferRawPropertySchema<P extends Property<any, any, any> | Schema<any, any>> = P extends Property<
+    any,
+    infer Raw,
+    any
+>
+    ? Raw
+    : P extends Schema<any, any>
+    ? inferRaw<P>
+    : never;
+
+export type inferParsedPropertySchema<P extends Property<any, any, any> | Schema<any, any>> = P extends Property<
+    any,
+    any,
+    infer Parsed
+>
+    ? Parsed
+    : P extends Schema<any, any>
+    ? inferParsed<P>
+    : never;
+
+export type inferRawKey<
+    ParsedKey extends string | number | symbol,
+    P extends Property<any, any, any> | Schema<any, any>
+> = P extends Property<infer Raw, any, any> ? Raw : ParsedKey;

package/src/opik/rest_api/core/schemas/builders/object-like/getObjectLikeUtils.ts

@@ -0,0 +1,79 @@
+import { BaseSchema } from "../../Schema";
+import { filterObject } from "../../utils/filterObject";
+import { getErrorMessageForIncorrectType } from "../../utils/getErrorMessageForIncorrectType";
+import { isPlainObject } from "../../utils/isPlainObject";
+import { getSchemaUtils } from "../schema-utils";
+import { ObjectLikeSchema, ObjectLikeUtils } from "./types";
+
+export function getObjectLikeUtils<Raw, Parsed>(schema: BaseSchema<Raw, Parsed>): ObjectLikeUtils<Raw, Parsed> {
+    return {
+        withParsedProperties: (properties) => withParsedProperties(schema, properties),
+    };
+}
+
+/**
+ * object-like utils are defined in one file to resolve issues with circular imports
+ */
+
+export function withParsedProperties<RawObjectShape, ParsedObjectShape, Properties>(
+    objectLike: BaseSchema<RawObjectShape, ParsedObjectShape>,
+    properties: { [K in keyof Properties]: Properties[K] | ((parsed: ParsedObjectShape) => Properties[K]) }
+): ObjectLikeSchema<RawObjectShape, ParsedObjectShape & Properties> {
+    const objectSchema: BaseSchema<RawObjectShape, ParsedObjectShape & Properties> = {
+        parse: (raw, opts) => {
+            const parsedObject = objectLike.parse(raw, opts);
+            if (!parsedObject.ok) {
+                return parsedObject;
+            }
+
+            const additionalProperties = Object.entries(properties).reduce<Record<string, any>>(
+                (processed, [key, value]) => {
+                    return {
+                        ...processed,
+                        [key]: typeof value === "function" ? value(parsedObject.value) : value,
+                    };
+                },
+                {}
+            );
+
+            return {
+                ok: true,
+                value: {
+                    ...parsedObject.value,
+                    ...(additionalProperties as Properties),
+                },
+            };
+        },
+
+        json: (parsed, opts) => {
+            if (!isPlainObject(parsed)) {
+                return {
+                    ok: false,
+                    errors: [
+                        {
+                            path: opts?.breadcrumbsPrefix ?? [],
+                            message: getErrorMessageForIncorrectType(parsed, "object"),
+                        },
+                    ],
+                };
+            }
+
+            // strip out added properties
+            const addedPropertyKeys = new Set(Object.keys(properties));
+            const parsedWithoutAddedProperties = filterObject(
+                parsed,
+                Object.keys(parsed).filter((key) => !addedPropertyKeys.has(key))
+            );
+
+            return objectLike.json(parsedWithoutAddedProperties as ParsedObjectShape, opts);
+        },
+
+        getType: () => objectLike.getType(),
+    };
+
+    return {
+        ...objectSchema,
+        ...getSchemaUtils(objectSchema),
+        ...getObjectLikeUtils(objectSchema),
+    };
+}

package/src/opik/rest_api/core/schemas/builders/object-like/index.ts

@@ -0,0 +1,2 @@
+export { getObjectLikeUtils, withParsedProperties } from "./getObjectLikeUtils";
+export type { ObjectLikeSchema, ObjectLikeUtils } from "./types";

package/src/opik/rest_api/core/schemas/builders/object-like/types.ts

@@ -0,0 +1,11 @@
+import { BaseSchema, Schema } from "../../Schema";
+
+export type ObjectLikeSchema<Raw, Parsed> = Schema<Raw, Parsed> &
+    BaseSchema<Raw, Parsed> &
+    ObjectLikeUtils<Raw, Parsed>;
+
+export interface ObjectLikeUtils<Raw, Parsed> {
+    withParsedProperties: <T extends Record<string, any>>(properties: {
+        [K in keyof T]: T[K] | ((parsed: Parsed) => T[K]);
+    }) => ObjectLikeSchema<Raw, Parsed & T>;
+}

package/src/opik/rest_api/core/schemas/builders/primitives/any.ts

@@ -0,0 +1,4 @@
+import { SchemaType } from "../../Schema";
+import { createIdentitySchemaCreator } from "../../utils/createIdentitySchemaCreator";
+
+export const any = createIdentitySchemaCreator<any>(SchemaType.ANY, (value) => ({ ok: true, value }));

package/src/opik/rest_api/core/schemas/builders/primitives/boolean.ts

@@ -0,0 +1,25 @@
+import { SchemaType } from "../../Schema";
+import { createIdentitySchemaCreator } from "../../utils/createIdentitySchemaCreator";
+import { getErrorMessageForIncorrectType } from "../../utils/getErrorMessageForIncorrectType";
+
+export const boolean = createIdentitySchemaCreator<boolean>(
+    SchemaType.BOOLEAN,
+    (value, { breadcrumbsPrefix = [] } = {}) => {
+        if (typeof value === "boolean") {
+            return {
+                ok: true,
+                value,
+            };
+        } else {
+            return {
+                ok: false,
+                errors: [
+                    {
+                        path: breadcrumbsPrefix,
+                        message: getErrorMessageForIncorrectType(value, "boolean"),
+                    },
+                ],
+            };
+        }
+    }
+);

package/src/opik/rest_api/core/schemas/builders/primitives/index.ts

@@ -0,0 +1,5 @@
+export { any } from "./any";
+export { boolean } from "./boolean";
+export { number } from "./number";
+export { string } from "./string";
+export { unknown } from "./unknown";

package/src/opik/rest_api/core/schemas/builders/primitives/number.ts

@@ -0,0 +1,25 @@
+import { SchemaType } from "../../Schema";
+import { createIdentitySchemaCreator } from "../../utils/createIdentitySchemaCreator";
+import { getErrorMessageForIncorrectType } from "../../utils/getErrorMessageForIncorrectType";
+
+export const number = createIdentitySchemaCreator<number>(
+    SchemaType.NUMBER,
+    (value, { breadcrumbsPrefix = [] } = {}) => {
+        if (typeof value === "number") {
+            return {
+                ok: true,
+                value,
+            };
+        } else {
+            return {
+                ok: false,
+                errors: [
+                    {
+                        path: breadcrumbsPrefix,
+                        message: getErrorMessageForIncorrectType(value, "number"),
+                    },
+                ],
+            };
+        }
+    }
+);

package/src/opik/rest_api/core/schemas/builders/primitives/string.ts

@@ -0,0 +1,25 @@
+import { SchemaType } from "../../Schema";
+import { createIdentitySchemaCreator } from "../../utils/createIdentitySchemaCreator";
+import { getErrorMessageForIncorrectType } from "../../utils/getErrorMessageForIncorrectType";
+
+export const string = createIdentitySchemaCreator<string>(
+    SchemaType.STRING,
+    (value, { breadcrumbsPrefix = [] } = {}) => {
+        if (typeof value === "string") {
+            return {
+                ok: true,
+                value,
+            };
+        } else {
+            return {
+                ok: false,
+                errors: [
+                    {
+                        path: breadcrumbsPrefix,
+                        message: getErrorMessageForIncorrectType(value, "string"),
+                    },
+                ],
+            };
+        }
+    }
+);

package/src/opik/rest_api/core/schemas/builders/primitives/unknown.ts

@@ -0,0 +1,4 @@
+import { SchemaType } from "../../Schema";
+import { createIdentitySchemaCreator } from "../../utils/createIdentitySchemaCreator";
+
+export const unknown = createIdentitySchemaCreator<unknown>(SchemaType.UNKNOWN, (value) => ({ ok: true, value }));

package/src/opik/rest_api/core/schemas/builders/record/index.ts

@@ -0,0 +1,2 @@
+export { record } from "./record";
+export type { BaseRecordSchema, RecordSchema } from "./types";