Merge pull request #4 from Start9Labs/chore/docs

chore: add some documentation and somet testing

Makefile

@@ -0,0 +1,6 @@
+TEST_FILES := $(shell find ./**/*.ts)
+
+
+test: $(TEST_FILES)
+	deno test test.ts
+	deno check mod.ts

compat/getConfig.ts

@@ -1,4 +1,3 @@
-
 import { YAML } from "../dependencies.ts";
 import { matches } from "../dependencies.ts";
 import { ExpectedExports } from "../types.ts";
@@ -8,7 +7,16 @@ const { any, string, dictionary } = matches;
 
 const matchConfig = dictionary([string, any]);
 
-export const getConfig = (spec: ConfigSpec): ExpectedExports.getConfig => async (effects) => {
+/**
+ * Call with the configuration to get a standard getConfig for the expected exports
+ * Assumption: start9/config.yaml is where the config will be stored
+ * Throws: Error if there is no file
+ * Throws: Error if the config.yaml isn't yaml nor config shape 
+ * @param spec
+ * @returns
+ */
+export const getConfig = (spec: ConfigSpec): ExpectedExports.getConfig =>
+  async (effects) => {
     const config = await effects
       .readFile({
         path: "start9/config.yaml",

compat/properties.ts

@@ -1,5 +1,5 @@
 import { YAML } from "../dependencies.ts";
-import { exists } from "../util.ts";
+import { exists } from "../exists.ts";
 import { Effects, ExpectedExports, Properties, ResultType } from "../types.ts";
 
 // deno-lint-ignore no-explicit-any
@@ -21,6 +21,8 @@ const noPropertiesFound: ResultType<Properties> = {
 } as const;
 /**
  * Default will pull from a file (start9/stats.yaml) expected to be made on the main volume
+ * Assumption: start9/stats.yaml is created by some process
+ * Throws: stats.yaml isn't yaml
  * @param effects
  * @returns
  */

compat/setConfig.ts

@@ -1,8 +1,15 @@
 import { YAML } from "../dependencies.ts";
-import { ExpectedExports, Effects, Config, SetResult, DependsOn } from "../types.ts";
+import {
+  Config,
+  DependsOn,
+  Effects,
+  ExpectedExports,
+  SetResult,
+} from "../types.ts";
 
 /**
  * Will set the config to the default start9/config.yaml
+ * Assumption: start9/config.yaml is the location of the configuration
  * @param effects
  * @param newConfig Config to be written to start9/config.yaml
  * @param depends_on This would be the depends on for condition depends_on
@@ -11,7 +18,7 @@ import { ExpectedExports, Effects, Config, SetResult, DependsOn } from "../types
 export const setConfig = async (
   effects: Effects,
   newConfig: Config,
-    dependsOn: DependsOn = {}
+  dependsOn: DependsOn = {},
 ) => {
   await effects.createDir({
     path: "start9",
@@ -27,7 +34,7 @@ export const setConfig = async (
     signal: "SIGTERM",
     "depends-on": dependsOn,
   };
-    return { result, };
+  return { result };
 };
 
-const _typeConversionCheck: ExpectedExports.setConfig = setConfig
+const _typeConversionCheck: ExpectedExports.setConfig = setConfig;

emver-lite/mod.ts

@@ -125,6 +125,12 @@ export class EmVer {
   public lessThan(other: EmVer): boolean {
     return !this.greaterThanOrEqual(other);
   }
+  /**
+   * Return a enum string that describes (used for switching/iffs)
+   * to know comparison
+   * @param other
+   * @returns
+   */
   public compare(other: EmVer) {
     if (this.equals(other)) {
       return "equal" as const;
@@ -134,6 +140,11 @@ export class EmVer {
       return "less" as const;
     }
   }
+  /**
+   * Used when sorting emver's in a list using the sort method
+   * @param other
+   * @returns
+   */
   public compareForSort(other: EmVer) {
     return matches.matches(this.compare(other))
       .when("equal", () => 0 as const)
@@ -237,6 +248,9 @@ export class Checker {
     public readonly check: (value: string | EmVer) => boolean,
   ) {}
 
+  /**
+   * Used when we want the `and` condition with another checker
+   */
   public and(...others: (Checker | string)[]): Checker {
     return new Checker((value) => {
       if (!this.check(value)) {
@@ -250,6 +264,10 @@ export class Checker {
       return true;
     });
   }
+
+  /**
+   * Used when we want the `or` condition with another checker
+   */
   public or(...others: (Checker | string)[]): Checker {
     return new Checker((value) => {
       if (this.check(value)) {
@@ -263,6 +281,11 @@ export class Checker {
       return false;
     });
   }
+
+  /**
+   * A useful example is making sure we don't match an exact version, like !=1.2.3
+   * @returns
+   */
   public not(): Checker {
     return new Checker((value) => !this.check(value));
   }

emver-lite/test.ts

@@ -1,21 +1,19 @@
-
 import { expect } from "https://deno.land/x/expect@v0.2.9/mod.ts";
-import { notRange, rangeAnd, rangeOf, rangeOr } from "./mod.ts";
+import { EmVer, notRange, rangeAnd, rangeOf, rangeOr } from "./mod.ts";
 const { test } = Deno;
 
-
 {
   const checker = rangeOf("*");
   test("rangeOf('*')", () => {
     expect(checker.check("1")).toBe(true);
     expect(checker.check("1.2")).toBe(true);
     expect(checker.check("1.2.3.4")).toBe(true);
-    })
+  });
   test("rangeOf('*') invalid", () => {
     expect(() => checker.check("a")).toThrow();
     expect(() => checker.check("")).toThrow();
     expect(() => checker.check("1..3")).toThrow();
-    })
+  });
 }
 
 {
@@ -24,25 +22,25 @@ const { test } = Deno;
     expect(checker.check("2")).toBe(true);
     expect(checker.check("1.2.3.5")).toBe(true);
     expect(checker.check("1.2.3.4.1")).toBe(true);
-    })
+  });
 
   test(`rangeOf(">1.2.3.4") invalid`, () => {
     expect(checker.check("1.2.3.4")).toBe(false);
     expect(checker.check("1.2.3")).toBe(false);
     expect(checker.check("1")).toBe(false);
-    })
+  });
 }
 {
   const checker = rangeOf("=1.2.3");
   test(`rangeOf("=1.2.3") valid`, () => {
     expect(checker.check("1.2.3")).toBe(true);
-    })
+  });
 
   test(`rangeOf("=1.2.3") invalid`, () => {
     expect(checker.check("2")).toBe(false);
     expect(checker.check("1.2.3.1")).toBe(false);
     expect(checker.check("1.2")).toBe(false);
-    })
+  });
 }
 {
   const checker = rangeOf(">=1.2.3.4");
@@ -51,12 +49,12 @@ const { test } = Deno;
     expect(checker.check("1.2.3.5")).toBe(true);
     expect(checker.check("1.2.3.4.1")).toBe(true);
     expect(checker.check("1.2.3.4")).toBe(true);
-    })
+  });
 
   test(`rangeOf(">=1.2.3.4") invalid`, () => {
     expect(checker.check("1.2.3")).toBe(false);
     expect(checker.check("1")).toBe(false);
-    })
+  });
 }
 {
   const checker = rangeOf("<1.2.3.4");
@@ -65,12 +63,12 @@ const { test } = Deno;
     expect(checker.check("1.2.3.5")).toBe(false);
     expect(checker.check("1.2.3.4.1")).toBe(false);
     expect(checker.check("1.2.3.4")).toBe(false);
-    })
+  });
 
   test(`rangeOf("<1.2.3.4") valid`, () => {
     expect(checker.check("1.2.3")).toBe(true);
     expect(checker.check("1")).toBe(true);
-    })
+  });
 }
 {
   const checker = rangeOf("<=1.2.3.4");
@@ -78,17 +76,16 @@ const { test } = Deno;
     expect(checker.check("2")).toBe(false);
     expect(checker.check("1.2.3.5")).toBe(false);
     expect(checker.check("1.2.3.4.1")).toBe(false);
-    })
+  });
 
   test(`rangeOf("<=1.2.3.4") valid`, () => {
     expect(checker.check("1.2.3")).toBe(true);
     expect(checker.check("1")).toBe(true);
     expect(checker.check("1.2.3.4")).toBe(true);
-    })
+  });
 }
 
 {
-
   const checkA = rangeOf(">1");
   const checkB = rangeOf("<=2");
 
@@ -97,15 +94,14 @@ const { test } = Deno;
     expect(checker.check("2")).toBe(true);
 
     expect(checker.check("1.1")).toBe(true);
-    })
+  });
   test(`simple and(checkers) invalid`, () => {
     expect(checker.check("2.1")).toBe(false);
     expect(checker.check("1")).toBe(false);
     expect(checker.check("0")).toBe(false);
-    })
+  });
 }
 {
-
   const checkA = rangeOf("<1");
   const checkB = rangeOf("=2");
 
@@ -113,19 +109,19 @@ const { test } = Deno;
   test(`simple or(checkers) valid`, () => {
     expect(checker.check("2")).toBe(true);
     expect(checker.check("0.1")).toBe(true);
-    })
+  });
   test(`simple or(checkers) invalid`, () => {
     expect(checker.check("2.1")).toBe(false);
     expect(checker.check("1")).toBe(false);
     expect(checker.check("1.1")).toBe(false);
-    })
+  });
 }
 {
-    const checker = rangeOf('1.2.*');
+  const checker = rangeOf("1.2.*");
   test(`rangeOf(1.2.*) valid`, () => {
     expect(checker.check("1.2")).toBe(true);
     expect(checker.check("1.2.1")).toBe(true);
-    })
+  });
   test(`rangeOf(1.2.*) invalid`, () => {
     expect(checker.check("1.3")).toBe(false);
     expect(checker.check("1.3.1")).toBe(false);
@@ -134,14 +130,12 @@ const { test } = Deno;
     expect(checker.check("1.1")).toBe(false);
     expect(checker.check("1")).toBe(false);
 
-
     expect(checker.check("2")).toBe(false);
-    })
+  });
 }
 
-
 {
-    const checker = notRange(rangeOf('1.2.*'));
+  const checker = notRange(rangeOf("1.2.*"));
   test(`notRange(rangeOf(1.2.*)) valid`, () => {
     expect(checker.check("1.3")).toBe(true);
     expect(checker.check("1.3.1")).toBe(true);
@@ -150,17 +144,16 @@ const { test } = Deno;
     expect(checker.check("1.1")).toBe(true);
     expect(checker.check("1")).toBe(true);
 
-
     expect(checker.check("2")).toBe(true);
-    })
+  });
   test(`notRange(rangeOf(1.2.*)) invalid `, () => {
     expect(checker.check("1.2")).toBe(false);
     expect(checker.check("1.2.1")).toBe(false);
-    })
+  });
 }
 
 {
-    const checker = rangeOf('!1.2.*');
+  const checker = rangeOf("!1.2.*");
   test(`!(rangeOf(1.2.*)) valid`, () => {
     expect(checker.check("1.3")).toBe(true);
     expect(checker.check("1.3.1")).toBe(true);
@@ -169,22 +162,21 @@ const { test } = Deno;
     expect(checker.check("1.1")).toBe(true);
     expect(checker.check("1")).toBe(true);
 
-
     expect(checker.check("2")).toBe(true);
-    })
+  });
   test(`!(rangeOf(1.2.*)) invalid `, () => {
     expect(checker.check("1.2")).toBe(false);
     expect(checker.check("1.2.1")).toBe(false);
-    })
+  });
 }
 
 {
   test(`no and ranges`, () => {
-        expect(() => rangeAnd()).toThrow()
+    expect(() => rangeAnd()).toThrow();
-    })
+  });
   test(`no or ranges`, () => {
-        expect(() => rangeOr()).toThrow()
+    expect(() => rangeOr()).toThrow();
-    })
+  });
 }
 {
   const checker = rangeOf("!>1.2.3.4");
@@ -192,13 +184,13 @@ const { test } = Deno;
     expect(checker.check("2")).toBe(false);
     expect(checker.check("1.2.3.5")).toBe(false);
     expect(checker.check("1.2.3.4.1")).toBe(false);
-    })
+  });
 
   test(`rangeOf("!>1.2.3.4") valid`, () => {
     expect(checker.check("1.2.3.4")).toBe(true);
     expect(checker.check("1.2.3")).toBe(true);
     expect(checker.check("1")).toBe(true);
-    })
+  });
 }
 
 test(">1 && =1.2", () => {
@@ -206,17 +198,14 @@ test(">1 && =1.2", () => {
 
   expect(checker.check("1.2")).toBe(true);
   expect(checker.check("1.2.1")).toBe(false);
-
+});
-})
 test("=1 || =2", () => {
   const checker = rangeOf("=1 || =2");
 
   expect(checker.check("1")).toBe(true);
   expect(checker.check("2")).toBe(true);
   expect(checker.check("3")).toBe(false);
-
+});
-})
-
 
 test(">1 && =1.2 || =2", () => {
   const checker = rangeOf(">1 && =1.2 || =2");
@@ -225,8 +214,7 @@ test(">1 && =1.2 || =2", () => {
   expect(checker.check("1")).toBe(false);
   expect(checker.check("2")).toBe(true);
   expect(checker.check("3")).toBe(false);
-
+});
-})
 
 test("&& before || order of operationns:  <1.5 && >1 || >1.5 && <3", () => {
   const checker = rangeOf("<1.5 && >1 || >1.5 && <3");
@@ -236,5 +224,21 @@ test("&& before || order of operationns:  <1.5 && >1 || >1.5 && <3", () => {
   expect(checker.check("1.5")).toBe(false);
   expect(checker.check("1")).toBe(false);
   expect(checker.check("3")).toBe(false);
+});
 
-})
+test("Compare function on the emver", () => {
+  const a = EmVer.from("1.2.3");
+  const b = EmVer.from("1.2.4");
+
+  expect(a.compare(b) === "less");
+  expect(b.compare(a) === "greater");
+  expect(a.compare(a) === "equal");
+});
+test("Compare for sort function on the emver", () => {
+  const a = EmVer.from("1.2.3");
+  const b = EmVer.from("1.2.4");
+
+  expect(a.compareForSort(b) === -1);
+  expect(b.compareForSort(a) === 1);
+  expect(a.compareForSort(a) === 0);
+});

test.ts

@@ -0,0 +1 @@
+import "./emver-lite/test.ts";