Merge pull request #166 from ThomasAribart/start-adding-jsdocs

Start adding jsdocs

package.json

@@ -24,7 +24,7 @@
   "dependencies": {
     "@babel/runtime": "^7.18.3",
     "@types/json-schema": "^7.0.9",
-    "ts-algebra": "^1.2.0"
+    "ts-algebra": "^1.2.2"
   },
   "devDependencies": {
     "@babel/cli": "^7.17.6",

src/definitions/extendedJsonSchema7.ts

@@ -2,8 +2,16 @@ import type { JSONSchema7 as OriginalJSONSchema7 } from "json-schema";
 
 import { $JSONSchema7 } from "./jsonSchema7";
 
+/**
+ * JSON Schema extension (i.e. additional custom fields)
+ */
 export type JSONSchema7Extension = Record<string, unknown>;
 
+/**
+ * Extended JSON Schema type constraint
+ * @param EXTENSION JSONSchema7Extension
+ * @returns Type
+ */
 export type ExtendedJSONSchema7<
   EXTENSION extends JSONSchema7Extension = JSONSchema7Extension,
 > =
@@ -62,10 +70,21 @@ export type ExtendedJSONSchema7<
       default?: unknown;
     } & Partial<EXTENSION>);
 
+/**
+ * Extended JSON Schema with reference type constraint
+ * @param EXTENSION JSONSchema7Extension
+ * @returns Type
+ */
 export type ExtendedJSONSchema7Reference<
   EXTENSION extends JSONSchema7Extension = JSONSchema7Extension,
 > = ExtendedJSONSchema7<EXTENSION> & { $id: string };
 
+/**
+ * Unextends a tuple of extended JSON Schemas
+ * @param EXTENSION JSONSchema7Extension
+ * @param EXTENDED_SCHEMAS ExtendedJSONSchema[]
+ * @returns ExtendedJSONSchema[]
+ */
 type UnextendJSONSchema7Tuple<
   EXTENSION extends JSONSchema7Extension,
   EXTENDED_SCHEMAS extends ExtendedJSONSchema7<EXTENSION>[],
@@ -83,15 +102,27 @@ type UnextendJSONSchema7Tuple<
     : never
   : [];
 
+/**
+ * Unextends a record of extended JSON Schemas
+ * @param EXTENSION JSONSchema7Extension
+ * @param EXTENDED_SCHEMA_RECORD Record<string, ExtendedJSONSchema>
+ * @returns Record<string, ExtendedJSONSchema>
+ */
 type UnextendJSONSchema7Record<
   EXTENSION extends JSONSchema7Extension,
-  SCHEMA_RECORD extends Record<string, unknown>,
+  EXTENDED_SCHEMA_RECORD extends Record<string, unknown>,
 > = {
-  [KEY in keyof SCHEMA_RECORD]: SCHEMA_RECORD[KEY] extends ExtendedJSONSchema7<EXTENSION>
-    ? UnextendJSONSchema7<EXTENSION, SCHEMA_RECORD[KEY]>
-    : SCHEMA_RECORD[KEY];
+  [KEY in keyof EXTENDED_SCHEMA_RECORD]: EXTENDED_SCHEMA_RECORD[KEY] extends ExtendedJSONSchema7<EXTENSION>
+    ? UnextendJSONSchema7<EXTENSION, EXTENDED_SCHEMA_RECORD[KEY]>
+    : EXTENDED_SCHEMA_RECORD[KEY];
 };
 
+/**
+ * Given an extended JSON Schema, recursively appends the `$JSONSchema7` symbol as optional property to have it actually extend the JSONSchema type constraint at all time
+ * @param EXTENSION JSONSchema7Extension
+ * @param EXTENDED_SCHEMA_RECORD ExtendedJSONSchema
+ * @returns ExtendedJSONSchema
+ */
 export type UnextendJSONSchema7<
   EXTENSION extends JSONSchema7Extension,
   EXTENDED_SCHEMA,

src/definitions/jsonSchema7.ts

@@ -1,8 +1,14 @@
 import type { JSONSchema7 as OriginalJSONSchema7 } from "json-schema";
 
-export const $JSONSchema7 = Symbol();
+export const $JSONSchema7 = Symbol("$JSONSchema7");
+/**
+ * Symbol used to make extended JSON schemas actually extend the JSONSchema type constraint at all time
+ */
 export type $JSONSchema7 = typeof $JSONSchema7;
 
+/**
+ * JSON Schema type constraint
+ */
 export type JSONSchema7 =
   | boolean
   | (Omit<
@@ -28,6 +34,7 @@ export type JSONSchema7 =
       | "examples"
       | "default"
     > & {
+      // Needed to have extended JSON schemas actually extend the JSONSchema type constraint at all time
       [$JSONSchema7]?: $JSONSchema7;
       const?: unknown;
       enum?: unknown;
@@ -60,4 +67,7 @@ export type JSONSchema7 =
       default?: unknown;
     });
 
+/**
+ * JSON Schema with reference type constraint
+ */
 export type JSONSchema7Reference = JSONSchema7 & { $id: string };

src/type-utils/get.ts

@@ -1,3 +1,10 @@
+/**
+ * Returns the (recursively) nested value of an object for a given path. Returns `DEFAULT` if no value is found.
+ * @param OBJECT Object
+ * @param PATH string[]
+ * @param DEFAULT Type
+ * @returns Type
+ */
 export type DeepGet<
   OBJECT,
   PATH extends string[],

src/type-utils/if.ts

@@ -1,3 +1,10 @@
+/**
+ * Return `THEN` if `CONDITION` extends `true`, `ELSE` otherwise
+ * @param CONDITION Boolean
+ * @param THEN Type
+ * @param ELSE Type
+ * @returns Type
+ */
 export type If<
   CONDITION extends boolean,
   THEN,

src/type-utils/join.ts

@@ -1,3 +1,9 @@
+/**
+ * Join a tuple of strings together
+ * @param STRINGS String[]
+ * @param SEPARATOR String
+ * @returns String
+ */
 export type Join<
   STRINGS extends string[],
   SEPARATOR extends string = ",",

src/type-utils/key.ts

@@ -1 +1,4 @@
+/**
+ * Any object key
+ */
 export type Key = string | number | symbol;

src/type-utils/narrow.ts

@@ -1,3 +1,8 @@
+/**
+ * Used to narrow the inferred generic type of a function
+ * @param INPUT Type
+ * @returns Type
+ */
 export type Narrow<INPUT> = INPUT extends Promise<infer AWAITED>
   ? Promise<Narrow<AWAITED>>
   : INPUT extends (...args: infer ARGS) => infer RETURN

src/type-utils/not.ts

@@ -1,5 +1,10 @@
-export type Not<CONDITION> = CONDITION extends false
+/**
+ * Return `true` if `BOOL` extends `false`, `false` if `BOOL` extends `true`, `never` otherwise
+ * @param BOOL Boolean
+ * @returns Boolean
+ */
+export type Not<BOOL> = BOOL extends false
   ? true
-  : CONDITION extends true
+  : BOOL extends true
   ? false
   : never;

src/type-utils/pop.ts

@@ -1,3 +1,8 @@
+/**
+ * Remove an item out of a union
+ * @param UNION Union
+ * @returns Type
+ */
 export type Pop<ARRAY extends unknown[]> = ARRAY extends
   | readonly [...infer ARRAY_BODY, unknown]
   | readonly [...infer ARRAY_BODY, unknown?]

src/type-utils/split.ts

@@ -1,12 +1,24 @@
 import type { Pop } from "./pop";
 
+/**
+ * Same as `Split` but doesn't remove the last value in case the SEPARATOR is an empty string
+ * @param STRING String
+ * @param SEPARATOR String
+ * @returns String[]
+ */
 type RecursiveSplit<
   STRING extends string,
   SEPARATOR extends string = "",
 > = STRING extends `${infer BEFORE}${SEPARATOR}${infer AFTER}`
   ? [BEFORE, ...RecursiveSplit<AFTER, SEPARATOR>]
   : [STRING];
 
+/**
+ * Given a string and a separator, split the string into an array of sub-strings delimited by the separator.
+ * @param STRING String
+ * @param SEPARATOR String
+ * @returns String[]
+ */
 export type Split<
   STRING extends string,
   SEPARATOR extends string = "",

src/type-utils/tail.ts

@@ -1,3 +1,8 @@
+/**
+ * Omit the first element of an array
+ * @param ARRAY Array
+ * @returns Array
+ */
 export type Tail<ARRAY extends unknown[]> = ARRAY extends readonly []
   ? ARRAY
   : ARRAY extends readonly [unknown?, ...infer ARRAY_TAIL]

yarn.lock

@@ -5712,10 +5712,10 @@ tr46@^2.1.0:
   dependencies:
     punycode "^2.1.1"
 
-ts-algebra@^1.2.0:
-  version "1.2.0"
-  resolved "https://registry.yarnpkg.com/ts-algebra/-/ts-algebra-1.2.0.tgz#f91c481207a770f0d14d055c376cbee040afdfc9"
-  integrity sha512-kMuJJd8B2N/swCvIvn1hIFcIOrLGbWl9m/J6O3kHx9VRaevh00nvgjPiEGaRee7DRaAczMYR2uwWvXU22VFltw==
+ts-algebra@^1.2.2:
+  version "1.2.2"
+  resolved "https://registry.yarnpkg.com/ts-algebra/-/ts-algebra-1.2.2.tgz#b75d301c28cd4126cd344760a47b43e48e2872e0"
+  integrity sha512-kloPhf1hq3JbCPOTYoOWDKxebWjNb2o/LKnNfkWhxVVisFFmMJPPdJeGoGmM+iRLyoXAR61e08Pb+vUXINg8aA==
 
 ts-jest@^28.0.2:
   version "28.0.8"