@badrap/valita - npm Package Compare versions

Comparing version 0.3.3 to 0.3.4

dist/cjs/index.d.ts

@@ -103,2 +103,3 @@ /**
  *
+ * @example
  * ```ts
@@ -127,17 +128,52 @@ * const t = v.object({ a: v.null(), b: v.null() });
 }
-interface Ok<T> {
+/**
+ * A successful validation/parsing result.
+ *
+ * Used in situations where both the parsing success and failure
+ * cases are returned as values.
+ */
+export type Ok<T> = {
     readonly ok: true;
     readonly value: T;
-}
-declare class Err {
-    private readonly issueTree;
-    readonly ok = false;
-    private _issues?;
-    private _message?;
-    constructor(issueTree: IssueTree);
-    get issues(): readonly Issue[];
-    get message(): string;
+};
+/**
+ * A validation/parsing failure.
+ *
+ * Used in situations where both the parsing success and failure
+ * cases are returned as values.
+ */
+export type Err = {
+    readonly ok: false;
+    readonly issues: readonly Issue[];
+    readonly message: string;
     throw(): never;
-}
+};
 /**
+ * A validation/parsing success or failure.
+ *
+ * Used by parsing-related methods where and both success and failure
+ * cases are returned as values (instead of raising an exception on failure).
+ * The most notable example is the `Type.try(...)` method.
+ *
+ * The `.ok` property can to assert whether the value represents a success or
+ * failure and access further information in a typesafe way.
+ *
+ * @example
+ * ```ts
+ * const t = v.string();
+ *
+ * // Make parsing fail or succeed about equally.
+ * const result = t.try(Math.random() < 0.5 ? "hello" : null);
+ *
+ * if (result.ok) {
+ *   // TypeScript allows accessing .value within this code block.
+ *   console.log(`Success: ${result.value}`);
+ * } else {
+ *   // TypeScript allows accessing .message within this code block.
+ *   console.log(`Failed: ${result.message}`);
+ * }
+ * ```
+ */
+export type ValitaResult<V> = Ok<V> | Err;
+/**
  * Create a value for returning a successful parsing result from chain().
@@ -169,4 +205,2 @@ *
 declare function err(error?: CustomError): Err;
-export type { Ok, Err };
-export type ValitaResult<V> = Ok<V> | Err;
 type RawResult<T> = undefined | Ok<T> | IssueTree;
@@ -206,2 +240,5 @@ declare const enum FuncMode {
 };
+/**
+ * A base class for all concreate validators/parsers.
+ */
 declare abstract class Type<Output = unknown> extends AbstractType<Output> {
@@ -213,2 +250,9 @@ nullable(): Type<null | Output>;
 }
+/**
+ * A validator/parser marked as "optional", signifying that their value can
+ * be missing from the parsed object.
+ *
+ * As such optionals can only be used as property validators within
+ * object validators.
+ */
 declare class Optional<Output = unknown> extends AbstractType<Output | undefined> {
@@ -215,0 +259,0 @@ private readonly type;

dist/cjs/index.js

@@ -180,2 +180,3 @@ "use strict";
  *
+ * @example
  * ```ts
@@ -214,3 +215,3 @@ * const t = v.object({ a: v.null(), b: v.null() });
 exports.ValitaError = ValitaError;
-class Err {
+class ErrImpl {
     constructor(issueTree) {
@@ -256,3 +257,3 @@ this.issueTree = issueTree;
 function err(error) {
-    return new Err({ ok: false, code: "custom_error", error });
+    return new ErrImpl({ ok: false, code: "custom_error", error });
 }
@@ -291,2 +292,5 @@ exports.err = err;
 }
+/**
+ * A base class for all concreate validators/parsers.
+ */
 class Type extends AbstractType {
@@ -317,3 +321,3 @@ nullable() {
         else {
-            return new Err(r);
+            return new ErrImpl(r);
         }
@@ -343,2 +347,9 @@ }
 }
+/**
+ * A validator/parser marked as "optional", signifying that their value can
+ * be missing from the parsed object.
+ *
+ * As such optionals can only be used as property validators within
+ * object validators.
+ */
 class Optional extends AbstractType {
@@ -345,0 +356,0 @@ constructor(type) {

dist/node-cjs/index.d.ts

@@ -103,2 +103,3 @@ /**
  *
+ * @example
  * ```ts
@@ -127,17 +128,52 @@ * const t = v.object({ a: v.null(), b: v.null() });
 }
-interface Ok<T> {
+/**
+ * A successful validation/parsing result.
+ *
+ * Used in situations where both the parsing success and failure
+ * cases are returned as values.
+ */
+export type Ok<T> = {
     readonly ok: true;
     readonly value: T;
-}
-declare class Err {
-    private readonly issueTree;
-    readonly ok = false;
-    private _issues?;
-    private _message?;
-    constructor(issueTree: IssueTree);
-    get issues(): readonly Issue[];
-    get message(): string;
+};
+/**
+ * A validation/parsing failure.
+ *
+ * Used in situations where both the parsing success and failure
+ * cases are returned as values.
+ */
+export type Err = {
+    readonly ok: false;
+    readonly issues: readonly Issue[];
+    readonly message: string;
     throw(): never;
-}
+};
 /**
+ * A validation/parsing success or failure.
+ *
+ * Used by parsing-related methods where and both success and failure
+ * cases are returned as values (instead of raising an exception on failure).
+ * The most notable example is the `Type.try(...)` method.
+ *
+ * The `.ok` property can to assert whether the value represents a success or
+ * failure and access further information in a typesafe way.
+ *
+ * @example
+ * ```ts
+ * const t = v.string();
+ *
+ * // Make parsing fail or succeed about equally.
+ * const result = t.try(Math.random() < 0.5 ? "hello" : null);
+ *
+ * if (result.ok) {
+ *   // TypeScript allows accessing .value within this code block.
+ *   console.log(`Success: ${result.value}`);
+ * } else {
+ *   // TypeScript allows accessing .message within this code block.
+ *   console.log(`Failed: ${result.message}`);
+ * }
+ * ```
+ */
+export type ValitaResult<V> = Ok<V> | Err;
+/**
  * Create a value for returning a successful parsing result from chain().
@@ -169,4 +205,2 @@ *
 declare function err(error?: CustomError): Err;
-export type { Ok, Err };
-export type ValitaResult<V> = Ok<V> | Err;
 type RawResult<T> = undefined | Ok<T> | IssueTree;
@@ -206,2 +240,5 @@ declare const enum FuncMode {
 };
+/**
+ * A base class for all concreate validators/parsers.
+ */
 declare abstract class Type<Output = unknown> extends AbstractType<Output> {
@@ -213,2 +250,9 @@ nullable(): Type<null | Output>;
 }
+/**
+ * A validator/parser marked as "optional", signifying that their value can
+ * be missing from the parsed object.
+ *
+ * As such optionals can only be used as property validators within
+ * object validators.
+ */
 declare class Optional<Output = unknown> extends AbstractType<Output | undefined> {
@@ -215,0 +259,0 @@ private readonly type;

dist/node-cjs/index.js

@@ -180,2 +180,3 @@ "use strict";
  *
+ * @example
  * ```ts
@@ -214,3 +215,3 @@ * const t = v.object({ a: v.null(), b: v.null() });
 exports.ValitaError = ValitaError;
-class Err {
+class ErrImpl {
     constructor(issueTree) {
@@ -256,3 +257,3 @@ this.issueTree = issueTree;
 function err(error) {
-    return new Err({ ok: false, code: "custom_error", error });
+    return new ErrImpl({ ok: false, code: "custom_error", error });
 }
@@ -291,2 +292,5 @@ exports.err = err;
 }
+/**
+ * A base class for all concreate validators/parsers.
+ */
 class Type extends AbstractType {
@@ -317,3 +321,3 @@ nullable() {
         else {
-            return new Err(r);
+            return new ErrImpl(r);
         }
@@ -343,2 +347,9 @@ }
 }
+/**
+ * A validator/parser marked as "optional", signifying that their value can
+ * be missing from the parsed object.
+ *
+ * As such optionals can only be used as property validators within
+ * object validators.
+ */
 class Optional extends AbstractType {
@@ -345,0 +356,0 @@ constructor(type) {

package.json

 {
   "name": "@badrap/valita",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "A validation & parsing library for TypeScript",
@@ -5,0 +5,0 @@ "main": "./dist/cjs/index.js",

README.md

@@ -9,3 +9,3 @@ # @badrap/valita [![tests](https://github.com/badrap/valita/workflows/tests/badge.svg)](https://github.com/badrap/valita/actions?query=workflow%3Atests) [![npm](https://img.shields.io/npm/v/@badrap/valita.svg)](https://www.npmjs.com/package/@badrap/valita)
   v.object({ type: v.literal("train") }),
-  v.object({ type: v.literal("automobile"), make: v.string() })
+  v.object({ type: v.literal("automobile"), make: v.string() }),
 );
@@ -22,2 +22,3 @@ vehicle.parse({ type: "bike" });
 ### Goals
+
 1. **Input Validation & Parsing**: The fundamental goal of the library is to ensure that incoming data, which might not be from a trusted source, aligns with the predetermined format.
@@ -28,2 +29,3 @@ 2. **Minimalism**: Deliver a streamlined and concentrated library that offers just the essentials.
 ### Non-Goals:
+
 1. **Data Definition**: The library is designed to validate and parse input data as it enters the program, rather than serving as an exhaustive tool for defining all types within the program after obtaining input.
@@ -47,52 +49,2 @@ 2. **Extensive Built-In Formats**: The library does not prioritize having a large array of built-in validation formats out of the box.
 
-## Docs aren't my forté
-
-A motivating example in lack of any better documentation:
-
-```ts
-import * as v from "@badrap/valita";
-
-const Pet = v.object({
-  type: v.union(v.literal("dog"), v.literal("cat")),
-  name: v.string(),
-});
-
-const Person = v.object({
-  name: v.string(),
-  age: v.number(),
-  pets: v.array(Pet).optional(),
-});
-```
-
-Now `Person.parse(value)` returns `value` if it matches the Person schema - or throws an error otherwise.
-
-```ts
-const grizzlor = Person.parse({
-  name: "Grizzlor",
-  age: 101,
-  pets: [
-    { type: "cat", name: "Mittens" },
-    { type: "cat", name: "Parsley" },
-    { type: "cat", name: "Lulu" },
-    { type: "cat", name: "Thomas Percival Meowther III" },
-  ],
-});
-```
-
-The real magic here comes from TypeScript's type inference. The inferred type for `grizzlor` is:
-
-```ts
-const grizzlor: {
-  name: string;
-  age: number;
-  pets?: { type: "dog" | "cat"; name: string }[] | undefined;
-};
-```
-
-You can use `Infer<T>` to get your mitts on the inferred type in your code:
-
-```ts
-type PersonType = v.Infer<typeof Person>;
-```
-
 ## API Reference
@@ -368,3 +320,3 @@
 
-_Note that TypeScript needs an explicit type cast as it cannot interfere return types of recursive functions. That's why the variable is typed as `v.Type<T>`._
+_Note that TypeScript needs an explicit type cast as it cannot infer return types of recursive functions. That's why the variable is typed as `v.Type<T>`._
 
@@ -371,0 +323,0 @@ ### Validating Self-Referencing Schemas

src/index.ts

@@ -234,2 +234,3 @@ /**
  *
+ * @example
  * ```ts
@@ -270,8 +271,55 @@ * const t = v.object({ a: v.null(), b: v.null() });
 
-interface Ok<T> {
+/**
+ * A successful validation/parsing result.
+ *
+ * Used in situations where both the parsing success and failure
+ * cases are returned as values.
+ */
+export type Ok<T> = {
   readonly ok: true;
   readonly value: T;
-}
+};
 
-class Err {
+/**
+ * A validation/parsing failure.
+ *
+ * Used in situations where both the parsing success and failure
+ * cases are returned as values.
+ */
+export type Err = {
+  readonly ok: false;
+  readonly issues: readonly Issue[];
+  readonly message: string;
+  throw(): never;
+};
+
+/**
+ * A validation/parsing success or failure.
+ *
+ * Used by parsing-related methods where and both success and failure
+ * cases are returned as values (instead of raising an exception on failure).
+ * The most notable example is the `Type.try(...)` method.
+ *
+ * The `.ok` property can to assert whether the value represents a success or
+ * failure and access further information in a typesafe way.
+ *
+ * @example
+ * ```ts
+ * const t = v.string();
+ *
+ * // Make parsing fail or succeed about equally.
+ * const result = t.try(Math.random() < 0.5 ? "hello" : null);
+ *
+ * if (result.ok) {
+ *   // TypeScript allows accessing .value within this code block.
+ *   console.log(`Success: ${result.value}`);
+ * } else {
+ *   // TypeScript allows accessing .message within this code block.
+ *   console.log(`Failed: ${result.message}`);
+ * }
+ * ```
+ */
+export type ValitaResult<V> = Ok<V> | Err;
+
+class ErrImpl implements Err {
   readonly ok = false;
@@ -336,8 +384,5 @@ private _issues?: Issue[];
 function err(error?: CustomError): Err {
-  return new Err({ ok: false, code: "custom_error", error });
+  return new ErrImpl({ ok: false, code: "custom_error", error });
 }
 
-export type { Ok, Err };
-export type ValitaResult<V> = Ok<V> | Err;
-
 type RawResult<T> = undefined | Ok<T> | IssueTree;
@@ -425,2 +470,5 @@
 
+/**
+ * A base class for all concreate validators/parsers.
+ */
 abstract class Type<Output = unknown> extends AbstractType<Output> {
@@ -451,3 +499,3 @@ nullable(): Type<null | Output> {
     } else {
-      return new Err(r);
+      return new ErrImpl(r);
     }
@@ -477,2 +525,9 @@ }
 
+/**
+ * A validator/parser marked as "optional", signifying that their value can
+ * be missing from the parsed object.
+ *
+ * As such optionals can only be used as property validators within
+ * object validators.
+ */
 class Optional<Output = unknown> extends AbstractType<Output | undefined> {
@@ -479,0 +534,0 @@ readonly name = "optional";

No alert changes

Improved metrics

Total package byte prevSize

410674

increased by1.74%

Lines of code

7523

increased by2.54%

Worsened metrics

Number of lines in readme file

345

decreased by-12.21%

No dependency changes