arktype - npm Package Compare versions

Comparing version 2.0.0-rc.14 to 2.0.0-rc.15

out/methods/base.d.ts

@@ -12,3 +12,14 @@ import type { ArkErrors, BaseRoot, Disjoint, JsonSchema, MetaSchema, Morph, PredicateCast, Predicate as PredicateFn, UndeclaredKeyBehavior } from "@ark/schema";
     [inferred]: t;
+    /**
+     * The top-level generic parameter accepted by the `Type`.\
+     * Potentially includes morphs and subtype constraints not reflected
+     *   in the types fully-inferred input (via `inferIn`) or output (via `infer` or `inferOut`).
+     * @example type A = type.infer<[typeof T.t, '[]']>
+     */
     t: t;
+    /**
+     * A type representing the output the `Type` will return (after morphs are applied to valid input)
+     * @example export type MyType = typeof MyType.infer
+     * @example export interface MyType extends Identity<typeof MyType.infer> {}
+     */
     infer: this["inferOut"];
@@ -19,2 +30,6 @@ inferBrandableIn: distill.brandable.In<t>;
     inferOut: distill.Out<t>;
+    /**
+     * A type representing the input the `Type` will accept (before morphs are applied)
+     * @example export type MyTypeInput = typeof MyType.inferIn
+     */
     inferIn: distill.In<t>;
@@ -24,2 +39,3 @@ inferredOutIsIntrospectable: t extends InferredMorph<any, infer o> ? [
     ] extends [anyOrNever] ? true : o extends To ? true : false : unknown extends t ? boolean : true;
+    /** Internal JSON representation of this `Type` */
     json: Json;
@@ -34,3 +50,13 @@ toJSON(): Json;
     $: Scope<$>;
+    /**
+     * Validate data, throwing `type.errors` instance on failure
+     * @returns a valid value
+     * @example const validData = T.assert(rawData)
+     */
     assert(data: unknown): this["infer"];
+    /**
+     * Check if data matches the input shape.
+     * Doesn't process any morphs, but does check narrows.
+     * @example type({ foo: "number" }).allows({ foo: "bar" }) // false
+     */
     allows(data: unknown): data is this["inferIn"];
@@ -41,14 +67,75 @@ traverse(data: unknown): this["infer"] | ArkErrors;
     describe(description: string): this;
+    /**
+     * Create a copy of this `Type` with updated unknown key behavior
+     * - `ignore`: ignore unknown properties (default)
+     * - 'reject': disallow objects with unknown properties
+     * - 'delete': clone the object and keep only known properties
+     */
     onUndeclaredKey(behavior: UndeclaredKeyBehavior): this;
+    /**
+     * Create a copy of this `Type` with updated unknown key behavior\
+     * The behavior applies to the whole object tree, not just the immediate properties.
+     * - `ignore`: ignore unknown properties (default)
+     * - 'reject': disallow objects with unknown properties
+     * - 'delete': clone the object and keep only known properties
+     */
     onDeepUndeclaredKey(behavior: UndeclaredKeyBehavior): this;
+    /**
+     * Identical to `assert`, but with a typed input as a convenience for providing a typed value.
+     * @example const ConfigT = type({ foo: "string" }); export const config = ConfigT.from({ foo: "bar" })
+     */
     from(literal: this["inferIn"]): this["infer"];
+    /**
+     * Cast the way this `Type` is inferred (has no effect at runtime).
+     * const branded = type(/^a/).as<`a${string}`>() // Type<`a${string}`>
+     */
     as<t = unset>(...args: validateChainedAsArgs<t>): instantiateType<t, $>;
+    /**
+     * A `Type` representing the deeply-extracted input of the `Type` (before morphs are applied).
+     * @example const inputT = T.in
+     */
     get in(): instantiateType<this["inferBrandableIn"], $>;
+    /**
+     * A `Type` representing the deeply-extracted output of the `Type` (after morphs are applied).\
+     * **IMPORTANT**: If your type includes morphs, their output will likely be unknown
+     *   unless they were defined with an explicit output validator via `.to(outputType)`, `.pipe(morph, outputType)`, etc.
+     * @example const outputT = T.out
+     */
     get out(): instantiateType<this["inferIntrospectableOut"], $>;
+    /**
+     * Intersect another `Type` definition, returning an introspectable `Disjoint` if the result is unsatisfiable.
+     * @example const intersection = type({ foo: "number" }).intersect({ bar: "string" }) // Type<{ foo: number; bar: string }>
+     * @example const intersection = type({ foo: "number" }).intersect({ foo: "string" }) // Disjoint
+     */
     intersect<const def, r = type.infer<def, $>>(def: type.validate<def, $>): instantiateType<inferIntersection<t, r>, $> | Disjoint;
+    /**
+     * Intersect another `Type` definition, throwing an error if the result is unsatisfiable.
+     * @example const intersection = type({ foo: "number" }).intersect({ bar: "string" }) // Type<{ foo: number; bar: string }>
+     */
     and<const def, r = type.infer<def, $>>(def: type.validate<def, $>): instantiateType<inferIntersection<t, r>, $>;
+    /**
+     * Union another `Type` definition.\
+     * If the types contain morphs, input shapes should be distinct. Otherwise an error will be thrown.
+     * @example const union = type({ foo: "number" }).or({ foo: "string" }) // Type<{ foo: number } | { foo: string }>
+     * @example const union = type("string.numeric.parse").or("number") // Type<((In: string) => Out<number>) | number>
+     */
     or<const def, r = type.infer<def, $>>(def: type.validate<def, $>): instantiateType<t | r, $>;
+    /**
+     * Add a custom predicate to this `Type`.
+     * @example const nan = type('number').narrow(n => Number.isNaN(n)) // Type<number>
+     * @example const foo = type("string").narrow((s): s is `foo${string}` => s.startsWith('foo') || ctx.mustBe('string starting with "foo"')) // Type<"foo${string}">
+     * @example const unique = type('string[]').narrow((a, ctx) => new Set(a).size === a.length || ctx.mustBe('array with unique elements'))
+     */
     narrow<narrowed extends this["infer"] = never, r = [narrowed] extends [never] ? t extends InferredMorph<infer i, infer o> ? o extends To ? (In: i) => To<applyConstraintSchema<o[1], "predicate", PredicateFn>> : (In: i) => Out<applyConstraintSchema<o[1], "predicate", PredicateFn>> : applyConstraintSchema<t, "predicate", PredicateFn> : t extends InferredMorph<infer i, infer o> ? o extends To ? (In: i) => To<narrowed> : (In: i) => Out<narrowed> : narrowed>(predicate: PredicateFn<this["infer"]> | PredicateCast<this["infer"], narrowed>): instantiateType<r, $>;
     satisfying<narrowed extends this["inferIn"] = never, r = [narrowed] extends [never] ? applyConstraintSchema<t, "predicate", PredicateFn> : t extends InferredMorph<any, infer o> ? (In: narrowed) => o : narrowed>(predicate: PredicateFn<this["inferIn"]> | PredicateCast<this["inferIn"], narrowed>): instantiateType<r, $>;
+    /**
+     * Create a `Type` for array with elements of this `Type`
+     * @example const T = type(/^foo/); const array = T.array() // Type<string[]>
+     */
     array(): ArrayType<t[], $>;
+    /**
+     * Morph this `Type` through a chain of morphs.
+     * @example const dedupe = type('string[]').pipe(a => Array.from(new Set(a)))
+     * @example type({codes: 'string.numeric[]'}).pipe(obj => obj.codes).to('string.numeric.parse[]')
+     */
     pipe: ChainedPipes<t, $>;
@@ -64,2 +151,10 @@ equals<const def>(def: type.validate<def, $>): boolean;
     optional<r = applyAttribute<t, Optional>>(): instantiateType<r, $>;
+    /**
+     * Add a default value for this `Type` when it is used as a property.\
+     * Default value should be a valid input value for this `Type, or a function that returns a valid input value.\
+     * If the type has a morph, it will be applied to the default value.
+     * @example const withDefault = type({ foo: type("string").default("bar") }); withDefault({}) // { foo: "bar" }
+     * @example const withFactory = type({ foo: type("number[]").default(() => [1])) }); withFactory({baz: 'a'}) // { foo: [1], baz: 'a' }
+     * @example const withMorph = type({ foo: type("string.numeric.parse").default("123") }); withMorph({}) // { foo: 123 }
+     */
     default<const value extends this["inferIn"], r = applyAttribute<t, Default<value>>>(value: DefaultFor<value>): instantiateType<r, $>;
@@ -66,0 +161,0 @@ /** @deprecated */

out/methods/morph.d.ts

@@ -6,4 +6,8 @@ import type { inferPipe } from "../keywords/inference.ts";
 interface Type<out t = unknown, $ = {}> extends BaseType<t, $> {
+    /**
+     * Append extra validation shape on the pipe output
+     * @example type({codes: 'string.numeric[]'}).pipe(obj => obj.codes).to('string.numeric.parse[]')
+     */
     to<const def, r = type.infer<def, $>>(def: type.validate<def, $>): Type<inferPipe<t, r>, $>;
 }
 export type { Type as MorphType };

out/methods/object.d.ts

@@ -16,15 +16,39 @@ import type { BaseMappedPropInner, OptionalMappedPropInner, Prop } from "@ark/schema";
     keyof(): instantiateType<arkKeyOf<t>, $>;
+    /**
+     * Get the `Type` of a property of this `Type<object>`.
+     * @example type({ foo: "string" }).get("foo") // Type<string>
+     */
     get<const k1 extends arkIndexableOf<t>, r = arkGet<t, k1>>(k1: k1 | type.cast<k1>): instantiateType<r, $>;
     get<const k1 extends arkIndexableOf<t>, const k2 extends arkIndexableOf<arkGet<t, k1>>>(k1: k1 | type.cast<k1>, k2: k2 | type.cast<k2>): instantiateType<arkGet<arkGet<t, k1>, k2>, $> extends infer r ? r : never;
     get<const k1 extends arkIndexableOf<t>, const k2 extends arkIndexableOf<arkGet<t, k1>>, const k3 extends arkIndexableOf<arkGet<arkGet<t, k1>, k2>>, r = arkGet<arkGet<arkGet<t, k1>, k2>, k3>>(k1: k1 | type.cast<k1>, k2: k2 | type.cast<k2>, k3: k3 | type.cast<k3>): instantiateType<r, $>;
+    /**
+     * Create a copy of this `Type` with only the specified properties.
+     * @example type({ foo: "string", bar: "number" }).pick("foo") // Type<{ foo: string }>
+     */
     pick<const key extends arkKeyOf<t> = never>(...keys: (key | type.cast<key>)[]): Type<{
         [k in keyof t as Extract<toArkKey<t, k>, key>]: t[k];
     }, $>;
+    /**
+     * Create a copy of this `Type` with all properties except the specified ones.
+     * @example type({ foo: "string", bar: "number" }).omit("foo") // Type<{ bar: number }>
+     */
     omit<const key extends arkKeyOf<t> = never>(...keys: (key | type.cast<key>)[]): Type<{
         [k in keyof t as Exclude<toArkKey<t, k>, key>]: t[k];
     }, $>;
+    /**
+     * Merge another `Type` definition, overriding properties of this `Type` with the duplicate keys.
+     * @example type({ a: "1", b: "2" }).merge({ b: "3", c: "4" }) // Type<{ a: 1, b: 3, c: 4 }>
+     */
     merge<const def, r = type.infer<def, $>>(def: type.validate<def, $> & (r extends object ? unknown : ErrorType<"Merged type must be an object", [actual: r]>)): Type<merge<t, r & object>, $>;
+    /**
+     * Create a copy of this `Type` with all properties required.
+     * @example const T = type({ "foo?"": "string" }).required() // Type<{ foo: string }>
+     */
     required(): Type<{
         [k in keyof t]-?: t[k];
     }, $>;
+    /**
+     * Create a copy of this `Type` with all properties optional.
+     * @example: const T = type({ foo: "string" }).optional() // Type<{ foo?: string }>
+     */
     partial(): Type<{
@@ -34,2 +58,6 @@ [k in keyof t]?: t[k];
     map<transformed extends listable<MappedTypeProp>>(flatMapEntry: (entry: typePropOf<t, $>) => transformed): Type<constructMapped<t, transformed>, $>;
+    /**
+     * List of property info of this `Type<object>`.
+     * @example type({ foo: "string = "" }).props // [{ kind: "required", key: "foo", value: Type<string>, default: "" }]
+     */
     props: array<typePropOf<t, $>>;
@@ -36,0 +64,0 @@ }

out/type.d.ts

@@ -17,2 +17,7 @@ import { ArkErrors, BaseRoot, type BaseParseOptions, type MetaSchema, type Morph, type Predicate, type RootSchema } from "@ark/schema";
     <const zero, const one, const rest extends array, r = Type<type.infer<[zero, one, ...rest], $>, $>>(_0: zero extends IndexZeroOperator ? zero : type.validate<zero, $>, _1: zero extends "keyof" ? type.validate<one, $> : zero extends "instanceof" ? conform<one, Constructor> : zero extends "===" ? conform<one, unknown> : conform<one, IndexOneOperator>, ..._2: zero extends "===" ? rest : zero extends "instanceof" ? conform<rest, readonly Constructor[]> : one extends TupleInfixOperator ? one extends ":" ? [Predicate<distill.In<type.infer<zero, $>>>] : one extends "=>" ? [Morph<distill.Out<type.infer<zero, $>>, unknown>] : one extends "@" ? [MetaSchema] : one extends "=" ? [DefaultFor<distill.In<type.infer<NoInfer<zero>, $>>>] : [type.validate<rest[0], $>] : []): r;
+    /**
+     * Error class for validation errors
+     * Calling type instance returns an instance of this class on failure
+     * @example if ( T(data) instanceof type.errors ) { ... }
+     */
     errors: typeof ArkErrors;
@@ -28,3 +33,14 @@ hkt: typeof Hkt;
     schema: SchemaParser<$>;
+    /**
+     * Create a `Type` that is satisfied only by a value strictly equal (`===`) to the argument passed to this function.
+     * @example const foo = type.unit('foo') // Type<'foo'>
+     * @example const sym: unique symbol = Symbol(); type.unit(sym) // Type<typeof sym>
+     */
     unit: UnitTypeParser<$>;
+    /**
+     * Create a `Type` that is satisfied only by a value strictly equal (`===`) to one of the arguments passed to this function.
+     * @example const enum = type.enumerated('foo', 'bar', obj) // obj is a by-reference object
+     * @example const tupleForm = type(['===', 'foo', 'bar', obj])
+     * @example const argsForm = type('===', 'foo', 'bar', obj)
+     */
     enumerated: EnumeratedTypeParser<$>;
@@ -31,0 +47,0 @@ }

package.json

 {
   "name": "arktype",
   "description": "TypeScript's 1:1 validator, optimized from editor to runtime",
-  "version": "2.0.0-rc.14",
+  "version": "2.0.0-rc.15",
   "license": "MIT",
@@ -37,4 +37,4 @@ "author": {
   "dependencies": {
-    "@ark/util": "0.16.0",
-    "@ark/schema": "0.16.0"
+    "@ark/util": "0.17.0",
+    "@ark/schema": "0.17.0"
   },
@@ -41,0 +41,0 @@ "publishConfig": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

239505

increased by3.23%

Lines of code

4664

increased by3.16%

Dependency changes

• + Added@ark/schema@0.17.0(transitive)

• + Added@ark/util@0.17.0(transitive)

• - Removed@ark/schema@0.16.0(transitive)

• - Removed@ark/util@0.16.0(transitive)

• Updated@ark/schema@0.17.0

• Updated@ark/util@0.17.0