schema-fun/dist/schemas.d.ts

JSON schema tools

import { type PropertyPath, type PropertyPathStr } from './paths.js';
export type JSONSchema = any;
export type Schema = JSONSchema;
export type EntitySchema = JSONSchema;
/**
 * A relationship storage class, which specifies how related documents are stored.
 *
 * - 'ref': Related documents are stored separately, and their IDs are recorded in the parent document. In place of the
 *   related object, the parent document has {"$ref": "<related document ID>"}.
 * - 'inverse-ref': Related documents are stored separately, and they include a foreign key property that refers to the
 *   parent document's ID.
 * - 'copy': A copy of each related document is stored directly in the parent document.
 */
export type RelationshipStorage = 'copy' | 'inverse-ref' | 'ref';
/**
 * A specification of a relationship between two schemas.
 */
export interface Relationship {
    path: PropertyPathStr;
    toMany: boolean;
    storage: RelationshipStorage;
    entityTypeName?: string;
    schemaRef?: string;
    /** The relationship property's schema. */
    schema: Schema;
    /**
     * The property path (in dot-and-bracket notation) of the foreign key in a relaitonship with storage class
     * 'inverse-ref'.
     */
    foreignKeyPath?: PropertyPathStr;
    /**
     * The depth of this relationship property from the nearest containing document, which may be the main schema or a
     * relationship with storage 'ref' or 'inverse-ref'. In storage-sensitive contexts, this tells you how many components
     * of Relationship.path are contained in the current document.
     */
    depthFromParent: number;
}
export type SchemaRefResolver = (schemaRef: string) => Schema | undefined;
/**
 * Expand references to other schemas.
 *
 * The returned schema may contain circular references and is therefore not serializable as JSON without special
 * handling.
 *
 * @param schema The schema to expand.
 * @param resolveSchemaRef A function that resolves references to other schemas.
 * @returns A new schema without schema references. It may contain circular references.
 */
export declare function expandSchemaReferences(schema: Schema, resolveSchemaRef: SchemaRefResolver): Promise<Schema | undefined>;
/**
 * Find one property in a schema, traversing referenced schemas if necessary.
 *
 * @param schema The schema to search.
 * @param path The property path to find, in dot-and-bracket notation or as an array.
 * @param resolveSchemaRef A function that resolves references to other schemas.
 * @returns The property schema if found, or else undefined.
 */
export declare function findPropertyInSchema(schema: Schema, path: PropertyPath, resolveSchemaRef: SchemaRefResolver): Schema | undefined;
/**
 * Find relationships in a schema.
 *
 * A relationship is a schema node that has a storage property; it describes a relationship between two documents. It
 * typically has a $ref property that refers to a different schema, but this is not necessary; the related document
 * type's schema may be embedded in the parent schema. The storage property indicates whether related documents are
 * stored
 * - As references,
 * - As inverse references
 * - Or inline, as copies of the related documents.
 * The list of relationships returned may optionally be limited to specified storage types using the allowedStorage
 * parameter.
 *
 * Relationships make sense in the context of some mechanism for finding or referring to documents. We call this a
 * storage mechanism; it may be a SQL or NoSQL database, a REST API, or something else.
 *
 * If limitToPath is set, this function will only traverse path through the schema hierarchy. Otherwise, it will find
 * all relationships.
 *
 * Since relationships my be cyclical, this function stops traversing the schema hierarchy whenever either
 * - The end of limitToPath is reached,
 * - limitToPath is not set and a specified maxDepth is reached,
 * - Or limitToPath is not set and the function encounters a schema node it has already visited.
 *
 * @param schema The schema in which to look for relationships.
 * @param resolveSchemaRef A function that resolves references to other schemas.
 * @param allowedStorage A list of storage classes. If specified, relationships with other storage classes are ignored.
 * @param limitToPath A property path (in dot-and-bracket notation or as an array) to traverse. If specified, only
 *   relationships in this path will be returned.
 * @param maxDepth A maximum depth to traverse. Ignored if limitToPath is set.
 * @param currentPath A parameter used when the function calls itself recursively. Should not be set by other callers.
 * @param nodesTraversedInPath A parameter used when the function calls itself recursively. Should not be set by other
 *   callers.
 * @param depthFromParent  A parameter used when the function calls itself recursively. Should not be set by other
 *   callers.
 * @returns A list of relationships contained in the schema.
 */
export declare function findRelationshipsInSchema(schema: Schema, resolveSchemaRef: SchemaRefResolver, allowedStorage?: RelationshipStorage[], limitToPath?: PropertyPath, maxDepth?: number | undefined, currentPath?: PropertyPath, nodesTraversedInPath?: Schema[], depthFromParent?: number): Relationship[];
/**
 * List all the transient properties of a schema.
 *
 * Transient properties are identified by the custom JSON schema attribute "transient" being set to true.
 *
 * If limitToPath is set, this function will only traverse path through the schema hierarchy. Otherwise, it will find
 * all relationships.
 *
 * Since relationships my be cyclical, this function stops traversing the schema hierarchy whenever either
 * - The end of limitToPath is reached,
 * - limitToPath is not set and a specified maxDepth is reached,
 * - Or limitToPath is not set and the function encounters a schema node it has already visited.
 *
 * @param schema The schema in which to look for transient properties.
 * @param resolveSchemaRef A function that resolves references to other schemas.
 * @param limitToPath A property path (in dot-and-bracket notation or as an array) to traverse. If specified, only
 *   relationships in this path will be returned.
 * @param maxDepth A maximum depth to traverse. Ignored if limitToPath is set.
 * @param currentPath A parameter used when the function calls itself recursively. Should not be set by other callers.
 * @param nodesTraversedInPath A parameter used when the function calls itself recursively. Should not be set by other
 *   callers.
 * @returns An array of transient property paths in dot-and-bracket notation
 */
export declare function findTransientPropertiesInSchema(schema: Schema, resolveSchemaRef: SchemaRefResolver, limitToPath?: PropertyPath, maxDepth?: number | undefined, currentPath?: PropertyPath, nodesTraversedInPath?: Schema[]): PropertyPathStr[];
/**
 * Determine whether a property is required by a schema.
 *
 * A property is required if all of its ancestors are required. If any ancestor is optional, the property is optional.
 * Therefore, calling this function on a subschema may produca a different result than calling it on the parent schema.
 *
 * "Required" status is not recorded in the property itself but in its parent object schema.
 *
 * For efficiency, this function does not always check that the specified property exists. It only tranverses the schema
 * until some non-required ancestor is encountered. If the property does not exist, this function will return false.
 *
 * @param schema The schema to search.
 * @param path The property path to check, in dot-and-bracket notation or as an array.
 * @param resolveSchemaRef A function that resolves references to other schemas.
 * @returns `true` if the property is required, or `false` if it is optional or does not exist.
 */
export declare function propertyIsRequiredInSchema(schema: Schema, path: PropertyPath, resolveSchemaRef: SchemaRefResolver): Schema | undefined;
//# sourceMappingURL=schemas.d.ts.map