@goast/core 0.7.0 → 0.7.1

package/dist/src/utils/generator.utils.d.ts

@@ -1 +1,8 @@
+/**
+ * Returns the specified value if it has been initialized. Throws an error if the value is `undefined`, which is used as
+ * the marker for a generator field that has not been set yet. Other values, including `null`, are returned as-is.
+ * @template T The type of the value.
+ * @param value The value to check.
+ * @returns The initialized value.
+ */
 export declare function getInitializedValue<T>(value: T | undefined): T;

package/dist/src/utils/generator.utils.js

@@ -1,3 +1,10 @@
+/**
+ * Returns the specified value if it has been initialized. Throws an error if the value is `undefined`, which is used as
+ * the marker for a generator field that has not been set yet. Other values, including `null`, are returned as-is.
+ * @template T The type of the value.
+ * @param value The value to check.
+ * @returns The initialized value.
+ */
 export function getInitializedValue(value) {
     if (value === undefined) {
         throw new Error('Generator not initialized.');

package/dist/src/utils/object.utils.d.ts

@@ -1,2 +1,18 @@
+/**
+ * Creates a proxy around an object whose property writes are stored separately, so the target is never modified.
+ * A read returns the written value, unless it is nullish. In that case the value of the target is returned.
+ * Only property reads and writes are intercepted. Other operations, such as `in` or `Object.keys`, use the target.
+ * @template T The type of the object.
+ * @param target The object to wrap.
+ * @param values The properties to write to the proxy right away.
+ * @returns A proxy that behaves like the target with the written values overriding it.
+ */
 export declare function createOverwriteProxy<T extends object>(target: T, values?: Partial<T>): T;
+/**
+ * Gets a nested property by following a path of keys.
+ * @param obj The object to read from.
+ * @param path The keys to follow, one per level. An empty path returns `obj` itself.
+ * @returns The value at the end of the path, or `undefined` if a value along the way is not an object, for example a
+ * primitive, `null` or a function, or if a key does not exist.
+ */
 export declare function getDeepProperty(obj: object, path: string[]): unknown;

package/dist/src/utils/object.utils.js

@@ -1,3 +1,12 @@
+/**
+ * Creates a proxy around an object whose property writes are stored separately, so the target is never modified.
+ * A read returns the written value, unless it is nullish. In that case the value of the target is returned.
+ * Only property reads and writes are intercepted. Other operations, such as `in` or `Object.keys`, use the target.
+ * @template T The type of the object.
+ * @param target The object to wrap.
+ * @param values The properties to write to the proxy right away.
+ * @returns A proxy that behaves like the target with the written values overriding it.
+ */
 export function createOverwriteProxy(target, values) {
     const proxy = new Proxy(target, new OverwriteProxyHandler());
     if (values) {
@@ -5,6 +14,13 @@ export function createOverwriteProxy(target, values) {
     }
     return proxy;
 }
+/**
+ * Gets a nested property by following a path of keys.
+ * @param obj The object to read from.
+ * @param path The keys to follow, one per level. An empty path returns `obj` itself.
+ * @returns The value at the end of the path, or `undefined` if a value along the way is not an object, for example a
+ * primitive, `null` or a function, or if a key does not exist.
+ */
 export function getDeepProperty(obj, path) {
     let current = obj;
     for (const key of path) {

package/dist/src/utils/schema-factory.d.ts

@@ -1,41 +1,238 @@
 import type { ApiSchema, ApiSchemaBase, ApiSchemaComponent, ApiSchemaExtensions, ApiSchemaProperty } from '../transform/api-types.ts';
+/**
+ * Base arguments accepted by every `create*Schema` and `create*Property` helper in this file. `required` is a list of
+ * property names that the helpers turn into a `Set`. A missing `name` is generated as `schema-<n>`, `id` defaults to
+ * the name, and `isNameGenerated` defaults to whether an `id` was given.
+ */
 export type TestSchema = Partial<Omit<ApiSchemaBase, 'required'>> & Partial<ApiSchemaComponent> & {
     required?: string[];
 };
+/**
+ * Arguments for `createOneOfSchema`: the base fields plus the `oneOf` branches to choose from.
+ * @see createOneOfSchema
+ */
 export type TestOneofSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'oneOf'>, 'kind'>>;
+/**
+ * Arguments for `createMultiTypeSchema`: the base fields, the `type` list, `properties` as a list of properties, and
+ * the keywords of the array, object, number and string kinds, since a `multi-type` schema can carry all of them.
+ * @see createMultiTypeSchema
+ */
 export type TestMultiTypeSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'multi-type'>, 'kind' | 'properties'>> & {
     properties?: ApiSchemaProperty[];
 };
+/**
+ * Arguments for `createStringSchema`: the base fields plus `pattern`, `minLength`, `maxLength` and `format`.
+ * @see createStringSchema
+ */
 export type TestStringSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'string'>, 'kind' | 'type'>>;
+/**
+ * Arguments for `createBooleanSchema`: the base fields plus `format`.
+ * @see createBooleanSchema
+ */
 export type TestBooleanSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'boolean'>, 'kind' | 'type'>>;
+/**
+ * Arguments for `createNullSchema`. A `null` schema has no keywords beyond the base fields.
+ * @see createNullSchema
+ */
 export type TestNullSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'null'>, 'kind' | 'type'>>;
+/**
+ * Arguments for `createNumberSchema`: the base fields plus `minimum`, `maximum` and `format`.
+ * @see createNumberSchema
+ */
 export type TestNumberSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'number'>, 'kind' | 'type'>>;
+/**
+ * Arguments for `createIntegerSchema`: the same fields as `createNumberSchema`.
+ * @see createIntegerSchema
+ */
 export type TestIntegerSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'integer'>, 'kind' | 'type'>>;
+/**
+ * Arguments for `createArraySchema`: the base fields plus `items`, `minItems` and `maxItems`.
+ * @see createArraySchema
+ */
 export type TestArraySchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'array'>, 'kind' | 'type'>>;
+/**
+ * Arguments for `createObjectSchema`: the base fields plus `properties` as a list, `additionalProperties`, and the
+ * `allOf` and `anyOf` branches.
+ * @see createObjectSchema
+ */
 export type TestObjectSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'object'>, 'kind' | 'type' | 'properties'>> & {
     properties?: ApiSchemaProperty[];
 };
+/**
+ * Arguments for `createCombinedSchema`: the base fields plus the `allOf` and `anyOf` branches.
+ * @see createCombinedSchema
+ */
 export type TestCombinedSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'combined'>, 'kind'>>;
+/**
+ * Arguments for `createUnknownSchema`. An `unknown` schema has no keywords beyond the base fields.
+ * @see createUnknownSchema
+ */
 export type TestUnknownSchema = TestSchema & Partial<Omit<ApiSchemaExtensions<'unknown'>, 'kind'>>;
+/**
+ * Creates a `oneOf` schema (kind `'oneOf'`) that matches exactly one of its `oneOf` branches. The branches default to
+ * an empty list.
+ * @param schema The base fields and the `oneOf` branches of the schema.
+ * @returns A `oneOf` schema with the given fields.
+ */
 export declare function createOneOfSchema(schema?: TestOneofSchema): ApiSchema<'oneOf'>;
+/**
+ * Creates a `multi-type` schema (kind `'multi-type'`) for a schema whose `type` lists several types. `type`, `allOf`
+ * and `anyOf` default to empty lists, and `properties` is converted into a map keyed by property name.
+ * @param schema The base fields and the keywords of the schema.
+ * @returns A `multi-type` schema with the given fields.
+ */
 export declare function createMultiTypeSchema(schema?: TestMultiTypeSchema): ApiSchema<'multi-type'>;
+/**
+ * Creates a `string` schema (kind and type `'string'`). Only the base fields and the `pattern`, `minLength`,
+ * `maxLength` and `format` keywords are read from the argument.
+ * @param schema The base fields and the string keywords of the schema.
+ * @returns A `string` schema with the given fields.
+ */
 export declare function createStringSchema(schema?: TestStringSchema): ApiSchema<'string'>;
+/**
+ * Creates a `boolean` schema (kind and type `'boolean'`). Only the base fields and `format` are read from the argument.
+ * @param schema The base fields and the `format` of the schema.
+ * @returns A `boolean` schema with the given fields.
+ */
 export declare function createBooleanSchema(schema?: TestBooleanSchema): ApiSchema<'boolean'>;
+/**
+ * Creates a `null` schema (kind and type `'null'`). Since `null` has no keywords, only the base fields are read from
+ * the argument.
+ * @param schema The base fields of the schema.
+ * @returns A `null` schema with the given fields.
+ */
 export declare function createNullSchema(schema?: TestNullSchema): ApiSchema<'null'>;
+/**
+ * Creates a `number` schema (kind and type `'number'`) for any numeric value, fractions included. Only the base fields
+ * and the `minimum`, `maximum` and `format` keywords are read from the argument.
+ * @param schema The base fields and the numeric keywords of the schema.
+ * @returns A `number` schema with the given fields.
+ * @see createIntegerSchema
+ */
 export declare function createNumberSchema(schema?: TestNumberSchema): ApiSchema<'number'>;
+/**
+ * Creates an `integer` schema (kind and type `'integer'`) for whole numbers. It reads the same keywords as
+ * {@link createNumberSchema}: `minimum`, `maximum` and `format`.
+ * @param schema The base fields and the numeric keywords of the schema.
+ * @returns An `integer` schema with the given fields.
+ * @see createNumberSchema
+ */
 export declare function createIntegerSchema(schema?: TestIntegerSchema): ApiSchema<'integer'>;
+/**
+ * Creates an `array` schema (kind and type `'array'`). `items` is taken as given, so leaving it out leaves the elements
+ * unconstrained, and `minItems` and `maxItems` are read from the argument.
+ * @param schema The base fields and the array keywords of the schema.
+ * @returns An `array` schema with the given fields.
+ */
 export declare function createArraySchema(schema?: TestArraySchema): ApiSchema<'array'>;
+/**
+ * Creates an `object` schema (kind and type `'object'`). `properties` is turned into a map keyed by property name,
+ * where a later property with the same name replaces an earlier one. `allOf` and `anyOf` default to empty lists.
+ * @param schema The base fields, properties and branches of the schema.
+ * @returns An `object` schema with the given fields.
+ */
 export declare function createObjectSchema(schema?: TestObjectSchema): ApiSchema<'object'>;
+/**
+ * Creates a `combined` schema (kind `'combined'`, with no `type`) composed of its `allOf` and `anyOf` branches. Both
+ * branch lists default to empty.
+ * @param schema The base fields and the branches of the schema.
+ * @returns A `combined` schema with the given fields.
+ */
 export declare function createCombinedSchema(schema?: TestCombinedSchema): ApiSchema<'combined'>;
+/**
+ * Creates an `unknown` schema (kind `'unknown'`), which has no kind-specific keywords. Only the base fields are read
+ * from the argument.
+ * @param schema The base fields of the schema.
+ * @returns An `unknown` schema with the given fields.
+ */
 export declare function createUnknownSchema(schema?: TestUnknownSchema): ApiSchema<'unknown'>;
+/**
+ * Creates a property whose schema is a `oneOf` schema with the branches given in `schema.oneOf`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `oneOf` schema, as for {@link createOneOfSchema}.
+ * @returns The property with the given name and a `oneOf` schema.
+ * @see createOneOfSchema
+ */
 export declare function createOneOfProperty(name: string, schema?: TestOneofSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is a `multi-type` schema with the `type` list and keywords given in `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `multi-type` schema, as for {@link createMultiTypeSchema}.
+ * @returns The property with the given name and a `multi-type` schema.
+ * @see createMultiTypeSchema
+ */
 export declare function createMultiTypeProperty(name: string, schema?: TestMultiTypeSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is a `string` schema with `pattern`, `minLength`, `maxLength` and `format` taken
+ * from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `string` schema, as for {@link createStringSchema}.
+ * @returns The property with the given name and a `string` schema.
+ * @see createStringSchema
+ */
 export declare function createStringProperty(name: string, schema?: TestStringSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is a `boolean` schema. Only the base fields and `format` of `schema` apply.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `boolean` schema, as for {@link createBooleanSchema}.
+ * @returns The property with the given name and a `boolean` schema.
+ * @see createBooleanSchema
+ */
 export declare function createBooleanProperty(name: string, schema?: TestBooleanSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is a `null` schema. Only the base fields of `schema` apply.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `null` schema, as for {@link createNullSchema}.
+ * @returns The property with the given name and a `null` schema.
+ * @see createNullSchema
+ */
 export declare function createNullProperty(name: string, schema?: TestNullSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is a `number` schema with `minimum`, `maximum` and `format` taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `number` schema, as for {@link createNumberSchema}.
+ * @returns The property with the given name and a `number` schema.
+ * @see createNumberSchema
+ */
 export declare function createNumberProperty(name: string, schema?: TestNumberSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is an `integer` schema with `minimum`, `maximum` and `format` taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `integer` schema, as for {@link createIntegerSchema}.
+ * @returns The property with the given name and an `integer` schema.
+ * @see createIntegerSchema
+ */
 export declare function createIntegerProperty(name: string, schema?: TestIntegerSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is an `array` schema with `items`, `minItems` and `maxItems` taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `array` schema, as for {@link createArraySchema}.
+ * @returns The property with the given name and an `array` schema.
+ * @see createArraySchema
+ */
 export declare function createArrayProperty(name: string, schema?: TestArraySchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is an `object` schema with `properties`, `additionalProperties`, `allOf` and `anyOf`
+ * taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `object` schema, as for {@link createObjectSchema}.
+ * @returns The property with the given name and an `object` schema.
+ * @see createObjectSchema
+ */
 export declare function createObjectProperty(name: string, schema?: TestObjectSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is a `combined` schema composed of the `allOf` and `anyOf` branches in `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `combined` schema, as for {@link createCombinedSchema}.
+ * @returns The property with the given name and a `combined` schema.
+ * @see createCombinedSchema
+ */
 export declare function createCombinedProperty(name: string, schema?: TestCombinedSchema): ApiSchemaProperty;
+/**
+ * Creates a property whose schema is an `unknown` schema, which carries only the base fields of `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `unknown` schema, as for {@link createUnknownSchema}.
+ * @returns The property with the given name and an `unknown` schema.
+ * @see createUnknownSchema
+ */
 export declare function createUnknownProperty(name: string, schema?: TestUnknownSchema): ApiSchemaProperty;

package/dist/src/utils/schema-factory.js

@@ -13,6 +13,12 @@ function createSchemaBase(schema) {
         custom: {},
     };
 }
+/**
+ * Creates a `oneOf` schema (kind `'oneOf'`) that matches exactly one of its `oneOf` branches. The branches default to
+ * an empty list.
+ * @param schema The base fields and the `oneOf` branches of the schema.
+ * @returns A `oneOf` schema with the given fields.
+ */
 export function createOneOfSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -20,6 +26,12 @@ export function createOneOfSchema(schema = {}) {
         oneOf: schema.oneOf ?? [],
     };
 }
+/**
+ * Creates a `multi-type` schema (kind `'multi-type'`) for a schema whose `type` lists several types. `type`, `allOf`
+ * and `anyOf` default to empty lists, and `properties` is converted into a map keyed by property name.
+ * @param schema The base fields and the keywords of the schema.
+ * @returns A `multi-type` schema with the given fields.
+ */
 export function createMultiTypeSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -30,6 +42,12 @@ export function createMultiTypeSchema(schema = {}) {
         anyOf: schema.anyOf ?? [],
     };
 }
+/**
+ * Creates a `string` schema (kind and type `'string'`). Only the base fields and the `pattern`, `minLength`,
+ * `maxLength` and `format` keywords are read from the argument.
+ * @param schema The base fields and the string keywords of the schema.
+ * @returns A `string` schema with the given fields.
+ */
 export function createStringSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -37,6 +55,11 @@ export function createStringSchema(schema = {}) {
         type: 'string',
     };
 }
+/**
+ * Creates a `boolean` schema (kind and type `'boolean'`). Only the base fields and `format` are read from the argument.
+ * @param schema The base fields and the `format` of the schema.
+ * @returns A `boolean` schema with the given fields.
+ */
 export function createBooleanSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -44,6 +67,12 @@ export function createBooleanSchema(schema = {}) {
         type: 'boolean',
     };
 }
+/**
+ * Creates a `null` schema (kind and type `'null'`). Since `null` has no keywords, only the base fields are read from
+ * the argument.
+ * @param schema The base fields of the schema.
+ * @returns A `null` schema with the given fields.
+ */
 export function createNullSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -51,6 +80,13 @@ export function createNullSchema(schema = {}) {
         type: 'null',
     };
 }
+/**
+ * Creates a `number` schema (kind and type `'number'`) for any numeric value, fractions included. Only the base fields
+ * and the `minimum`, `maximum` and `format` keywords are read from the argument.
+ * @param schema The base fields and the numeric keywords of the schema.
+ * @returns A `number` schema with the given fields.
+ * @see createIntegerSchema
+ */
 export function createNumberSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -58,6 +94,13 @@ export function createNumberSchema(schema = {}) {
         type: 'number',
     };
 }
+/**
+ * Creates an `integer` schema (kind and type `'integer'`) for whole numbers. It reads the same keywords as
+ * {@link createNumberSchema}: `minimum`, `maximum` and `format`.
+ * @param schema The base fields and the numeric keywords of the schema.
+ * @returns An `integer` schema with the given fields.
+ * @see createNumberSchema
+ */
 export function createIntegerSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -65,6 +108,12 @@ export function createIntegerSchema(schema = {}) {
         type: 'integer',
     };
 }
+/**
+ * Creates an `array` schema (kind and type `'array'`). `items` is taken as given, so leaving it out leaves the elements
+ * unconstrained, and `minItems` and `maxItems` are read from the argument.
+ * @param schema The base fields and the array keywords of the schema.
+ * @returns An `array` schema with the given fields.
+ */
 export function createArraySchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -73,6 +122,12 @@ export function createArraySchema(schema = {}) {
         items: schema.items ?? undefined,
     };
 }
+/**
+ * Creates an `object` schema (kind and type `'object'`). `properties` is turned into a map keyed by property name,
+ * where a later property with the same name replaces an earlier one. `allOf` and `anyOf` default to empty lists.
+ * @param schema The base fields, properties and branches of the schema.
+ * @returns An `object` schema with the given fields.
+ */
 export function createObjectSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -83,6 +138,12 @@ export function createObjectSchema(schema = {}) {
         anyOf: schema.anyOf ?? [],
     };
 }
+/**
+ * Creates a `combined` schema (kind `'combined'`, with no `type`) composed of its `allOf` and `anyOf` branches. Both
+ * branch lists default to empty.
+ * @param schema The base fields and the branches of the schema.
+ * @returns A `combined` schema with the given fields.
+ */
 export function createCombinedSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
@@ -91,42 +152,127 @@ export function createCombinedSchema(schema = {}) {
         anyOf: schema.anyOf ?? [],
     };
 }
+/**
+ * Creates an `unknown` schema (kind `'unknown'`), which has no kind-specific keywords. Only the base fields are read
+ * from the argument.
+ * @param schema The base fields of the schema.
+ * @returns An `unknown` schema with the given fields.
+ */
 export function createUnknownSchema(schema = {}) {
     return {
         ...createSchemaBase(schema),
         kind: 'unknown',
     };
 }
+/**
+ * Creates a property whose schema is a `oneOf` schema with the branches given in `schema.oneOf`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `oneOf` schema, as for {@link createOneOfSchema}.
+ * @returns The property with the given name and a `oneOf` schema.
+ * @see createOneOfSchema
+ */
 export function createOneOfProperty(name, schema = {}) {
     return { name, schema: createOneOfSchema(schema) };
 }
+/**
+ * Creates a property whose schema is a `multi-type` schema with the `type` list and keywords given in `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `multi-type` schema, as for {@link createMultiTypeSchema}.
+ * @returns The property with the given name and a `multi-type` schema.
+ * @see createMultiTypeSchema
+ */
 export function createMultiTypeProperty(name, schema = {}) {
     return { name, schema: createMultiTypeSchema(schema) };
 }
+/**
+ * Creates a property whose schema is a `string` schema with `pattern`, `minLength`, `maxLength` and `format` taken
+ * from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `string` schema, as for {@link createStringSchema}.
+ * @returns The property with the given name and a `string` schema.
+ * @see createStringSchema
+ */
 export function createStringProperty(name, schema = {}) {
     return { name, schema: createStringSchema(schema) };
 }
+/**
+ * Creates a property whose schema is a `boolean` schema. Only the base fields and `format` of `schema` apply.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `boolean` schema, as for {@link createBooleanSchema}.
+ * @returns The property with the given name and a `boolean` schema.
+ * @see createBooleanSchema
+ */
 export function createBooleanProperty(name, schema = {}) {
     return { name, schema: createBooleanSchema(schema) };
 }
+/**
+ * Creates a property whose schema is a `null` schema. Only the base fields of `schema` apply.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `null` schema, as for {@link createNullSchema}.
+ * @returns The property with the given name and a `null` schema.
+ * @see createNullSchema
+ */
 export function createNullProperty(name, schema = {}) {
     return { name, schema: createNullSchema(schema) };
 }
+/**
+ * Creates a property whose schema is a `number` schema with `minimum`, `maximum` and `format` taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `number` schema, as for {@link createNumberSchema}.
+ * @returns The property with the given name and a `number` schema.
+ * @see createNumberSchema
+ */
 export function createNumberProperty(name, schema = {}) {
     return { name, schema: createNumberSchema(schema) };
 }
+/**
+ * Creates a property whose schema is an `integer` schema with `minimum`, `maximum` and `format` taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `integer` schema, as for {@link createIntegerSchema}.
+ * @returns The property with the given name and an `integer` schema.
+ * @see createIntegerSchema
+ */
 export function createIntegerProperty(name, schema = {}) {
     return { name, schema: createIntegerSchema(schema) };
 }
+/**
+ * Creates a property whose schema is an `array` schema with `items`, `minItems` and `maxItems` taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `array` schema, as for {@link createArraySchema}.
+ * @returns The property with the given name and an `array` schema.
+ * @see createArraySchema
+ */
 export function createArrayProperty(name, schema = {}) {
     return { name, schema: createArraySchema(schema) };
 }
+/**
+ * Creates a property whose schema is an `object` schema with `properties`, `additionalProperties`, `allOf` and `anyOf`
+ * taken from `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `object` schema, as for {@link createObjectSchema}.
+ * @returns The property with the given name and an `object` schema.
+ * @see createObjectSchema
+ */
 export function createObjectProperty(name, schema = {}) {
     return { name, schema: createObjectSchema(schema) };
 }
+/**
+ * Creates a property whose schema is a `combined` schema composed of the `allOf` and `anyOf` branches in `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `combined` schema, as for {@link createCombinedSchema}.
+ * @returns The property with the given name and a `combined` schema.
+ * @see createCombinedSchema
+ */
 export function createCombinedProperty(name, schema = {}) {
     return { name, schema: createCombinedSchema(schema) };
 }
+/**
+ * Creates a property whose schema is an `unknown` schema, which carries only the base fields of `schema`.
+ * @param name The name of the property, used as its key in the `properties` of the parent schema.
+ * @param schema The arguments of the `unknown` schema, as for {@link createUnknownSchema}.
+ * @returns The property with the given name and an `unknown` schema.
+ * @see createUnknownSchema
+ */
 export function createUnknownProperty(name, schema = {}) {
     return { name, schema: createUnknownSchema(schema) };
 }

package/dist/src/utils/schema.utils.d.ts

@@ -1,6 +1,21 @@
 import type { OpenApiSchema } from '../parse/openapi-types.ts';
 import type { ApiSchema } from '../transform/api-types.ts';
+/**
+ * Merges the `allOf` and `anyOf` branches of a `combined` or `object` schema into one `object` schema, combining their
+ * properties, required names and additional properties. Required names from `anyOf` and composed `oneOf` branches are
+ * not taken over, and a property declared with conflicting kinds in different branches becomes a `oneOf` of both.
+ * @param schema The `combined` or `object` schema whose branches should be merged.
+ * @param ignoreNonObjectParts Whether non-object branches are tolerated. If `false`, a non-object branch makes the
+ * merge return `undefined`.
+ * @returns The merged `object` schema, or `undefined` if the merge is not possible or if there are no properties to
+ * merge and the additional properties do not change.
+ */
 export declare function resolveAnyOfAndAllOf(schema: ApiSchema<'combined' | 'object'>, ignoreNonObjectParts: boolean): ApiSchema<'object'> | undefined;
+/**
+ * The annotation keywords (`description`, `example` and `deprecated`) that do not count as defining a schema. A schema
+ * with a `$ref` that sets only these keywords is treated as a plain reference by {@link getSchemaReference}.
+ * @see getSchemaReference
+ */
 export declare const DEFAULT_IGNORED_SCHEMA_PROPERTIES: (keyof OpenApiSchema)[];
 /**
  * Retrieves the first schema reference and the reference chain of a given schema that

package/dist/src/utils/schema.utils.js

@@ -1,4 +1,14 @@
 import { isOpenApiObjectProperty } from '../internal-utils.js';
+/**
+ * Merges the `allOf` and `anyOf` branches of a `combined` or `object` schema into one `object` schema, combining their
+ * properties, required names and additional properties. Required names from `anyOf` and composed `oneOf` branches are
+ * not taken over, and a property declared with conflicting kinds in different branches becomes a `oneOf` of both.
+ * @param schema The `combined` or `object` schema whose branches should be merged.
+ * @param ignoreNonObjectParts Whether non-object branches are tolerated. If `false`, a non-object branch makes the
+ * merge return `undefined`.
+ * @returns The merged `object` schema, or `undefined` if the merge is not possible or if there are no properties to
+ * merge and the additional properties do not change.
+ */
 export function resolveAnyOfAndAllOf(schema, ignoreNonObjectParts) {
     if (!ignoreNonObjectParts && (hasInvalidSubSchema(schema.anyOf) || hasInvalidSubSchema(schema.allOf))) {
         return undefined;
@@ -182,6 +192,11 @@ function hasInvalidSubSchema(subSchemas) {
     return subSchemas.some((x) => x.kind !== 'object' &&
         (x.kind !== 'combined' || (!hasInvalidSubSchema(x.allOf) && !hasInvalidSubSchema(x.anyOf))));
 }
+/**
+ * The annotation keywords (`description`, `example` and `deprecated`) that do not count as defining a schema. A schema
+ * with a `$ref` that sets only these keywords is treated as a plain reference by {@link getSchemaReference}.
+ * @see getSchemaReference
+ */
 export const DEFAULT_IGNORED_SCHEMA_PROPERTIES = ['description', 'example', 'deprecated'];
 /**
  * Retrieves the first schema reference and the reference chain of a given schema that