chore: tweaks

Author: Mister-Hope

.oxlintrc.json

@@ -11,63 +11,92 @@
   },
   "plugins": ["import", "unicorn", "oxc", "promise", "jsdoc", "vitest", "node"],
   "rules": {
-    "catch-error-name": ["warn", { "name": "err" }],
-    "curly": ["off", "multi-line"],
+    // we should not enforce capitalized comments
+    "capitalized-comments": "off",
+    // prefer to export declarations instead of exporting at the end
     "group-exports": "off",
-    "id-length": "off",
+    // this rule is too restrictive
     "init-declarations": "off",
-    "max-dependencies": "off",
-    "max-lines": "off",
-    "max-lines-per-function": "off",
-    "max-params": ["warn", 4],
+    // allow continue in complicated loops
     "no-continue": "off",
+    // warn about console usage but allow it
     "no-console": "warn",
-    "no-duplicate-imports": "off",
+    // type imports can be duplicated with value imports
+    "no-duplicate-imports": ["error", { "allowSeparateTypeImports": true }],
+    // inline comments shall be allowed
+    "no-inline-comments": "off",
     "no-magic-numbers": "off",
-    // "no-magic-numbers": ["warn", { "ignore": [-1, 0, 1, 2] }],
+    // allow nested ternary for better readability in some cases
     "no-nested-ternary": "off",
+    // allow null usage
     "no-null": "off",
+    // ternary operator shall be allowed for simple expressions
     "no-ternary": "off",
-    "no-warning-comments": "off",
+    // normally we do not enforce numeric separator usage
+    "numeric-separators-style": "off",
+    // we prefer to sort imports with its pkg name
     "sort-imports": "off",
+    // object keys are not supposed to be sorted in many cases
     "sort-keys": "off",
 
+    // import plugin rules
+
     "import/exports-last": "off",
     // usually we just export vue components as default export without naming it
     "import/no-anonymous-default-export": "off",
     // a rule that shall not be enabled anyway
     "import/no-named-export": "off",
+    // allow importing stylesheets
     "import/no-unassigned-import": ["error", { "allow": ["**/*.css", "**/*.scss"] }],
-    // named export is preferred in our codebase
+    // named export is preferred
     "import/prefer-default-export": "off",
 
-    "jsdoc/check-tag-names": ["error", { "typed": true }],
-    "jsdoc/require-param": "off",
+    // jsdoc plugin rules
+
+    // duplicated typescript related jsdoc shall be warned
+    "jsdoc/check-tag-names": ["warn", { "typed": true }],
+    // we do not require types in jsdoc since we use TypeScript
     "jsdoc/require-param-type": "off",
-    "jsdoc/require-returns": "off",
+    // we do not require types in jsdoc since we use TypeScript
     "jsdoc/require-returns-type": "off",
 
     "promise/always-return": "off",
+    // we sometimes need to create new Promise instance
     "promise/avoid-new": "off",
+    // we prefer async/await syntax
     "promise/prefer-await-to-then": "off",
+
+    // unicorn plugin rules
+    // filename should not be enforced strictly, e.g. Vue SFC files shall be PascalCased
+    // we shall expect a project level setting
     "unicorn/filename-case": "off",
-    // toReversed can introduce memory overhead
+    // toReversed can introduce memory overhead,
+    // in some chained calls it is better to use reverse as the "reversed" array is also a temp variable.
     "unicorn/no-array-reverse": "off",
     // toSorted can introduce memory overhead
+    // in some chained calls it is better to use reverse as the "sorted" array is also a temp variable.
     "unicorn/no-array-sort": "off",
-    "unicorn/no-nested-ternary": "off",
-    // at is not supported by our target environments
+    // sometimes nested ternary is considerable
+    "unicorn/no-nested-ternary": "warn",
+    // Array.at() is too modern for browser targets
     "unicorn/prefer-at": "off",
-    "unicorn/prefer-global-this": "off",
+    // support starts with chrome71, firefox68. safari12.1, node12
+    // leaving it to warn for edge cases
+    "unicorn/prefer-global-this": "warn",
 
-    // seems conflicts with prettier
-    "number-literal-case": "off",
-    "numeric-separators-style": "off",
+    // stylistic rules with default being tweaked
 
-    // style rules
-    "capitalized-comments": "off",
-    "max-statements": ["warn", { "max": 30 }],
-    "no-inline-comments": "off"
+    "catch-error-name": ["warn", { "name": "err" }],
+    "curly": ["warn", "multi-line"],
+    "id-length": "off",
+    "max-dependencies": ["warn", { "ignoreTypeImports": true, "max": 15 }],
+    "max-lines": ["warn", { "max": 500, "skipBlankLines": true, "skipComments": true }],
+    "max-lines-per-function": [
+      "warn",
+      { "max": 100, "skipBlankLines": true, "skipComments": true }
+    ],
+    "max-params": ["warn", 4],
+    "max-statements": ["warn", { "max": 30 }]
   },
   "overrides": [
     {

.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-  "editor.defaultFormatter": "oxc.oxc-vscode"
+  "editor.defaultFormatter": "oxc.oxc-vscode",
+  "cSpell.words": ["crypted"]
 }

src/base64.ts

@@ -1,11 +1,13 @@
-/* oxlint-disable unicorn/prefer-code-point unicorn/prefer-math-trunc */
+// oxlint-disable unicorn/prefer-code-point unicorn/prefer-math-trunc
 import { BASE64_CODE, BASE64_INDEX } from "./constant.js";
 
 /**
  * Encodes a byte array to base64 with up to length bytes of input, using the custom bcrypt alphabet.
  *
  * @param byteArray Byte array
  * @param length Maximum input length
+ *
+ * @returns Encoded string
  */
 export const encodeBase64 = (byteArray: number[] | Buffer, length: number): string => {
   if (length <= 0 || length > byteArray.length) throw new Error(`Illegal length: ${length}`);
@@ -45,6 +47,8 @@ export const encodeBase64 = (byteArray: number[] | Buffer, length: number): stri
  *
  * @param contentString String to decode
  * @param length Maximum output length
+ *
+ * @returns Decoded bytes
  */
 // oxlint-disable-next-line max-statements
 export const decodeBase64 = (contentString: string, length: number): number[] => {

src/compare.ts

@@ -8,10 +8,13 @@ import { getIllegalArgumentsTypeError } from "./utils.js";
  *
  * @param content String to compare
  * @param hash Hash to test against
+ *
+ * @returns `true` if the string matches the hash, `false` otherwise
  */
 export const compareSync = (content: string, hash: string): boolean => {
-  if (typeof content !== "string" || typeof hash !== "string")
+  if (typeof content !== "string" || typeof hash !== "string") {
     throw getIllegalArgumentsTypeError(content, hash);
+  }
 
   if (hash.length !== 60) return false;
 
@@ -25,6 +28,8 @@ export const compareSync = (content: string, hash: string): boolean => {
  * @param hash Data to be compared to
  * @param progressCallback Callback successively called with the percentage of rounds completed
  *  (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
+ *
+ * @returns Promise resolving to `true` if the data matches the hash, `false` otherwise
  */
 export const compare = (
   content: string,

src/constant.ts

@@ -1,3 +1,5 @@
+// oxlint-disable no-magic-numbers
+
 export const BCRYPT_SALT_LEN = 16;
 
 export const GENERATE_SALT_DEFAULT_LOG2_ROUNDS = 10;

src/crypt.ts

@@ -157,6 +157,11 @@ const key = (key: number[], P: Int32Array<ArrayBuffer>, S: Int32Array<ArrayBuffe
 
 /**
  * Expensive key schedule Blowfish.
+ *
+ * @param data Data bytes
+ * @param key Key bytes
+ * @param P P-array
+ * @param S S-boxes
  */
 const expensiveKeyScheduleBlowFish = (
   data: number[],
@@ -213,6 +218,9 @@ const expensiveKeyScheduleBlowFish = (
  * @param salt Salt bytes to use
  * @param rounds Number of rounds
  * @param progressCallback Callback called with the current progress
+ * @param sync Whether to run synchronously
+ *
+ * @returns Crypted bytes
  */
 // oxlint-disable-next-line max-params
 export const crypt = (
@@ -237,6 +245,8 @@ export const crypt = (
 
   /**
    * Calculates the next round.
+   *
+   * @returns Next round or result
    */
   const next = (): Promise<number[] | void> | number[] | void => {
     if (progressCallback) progressCallback(round / rounds);
@@ -251,8 +261,9 @@ export const crypt = (
         if (Date.now() - start > MAX_EXECUTION_TIME) break;
       }
     } else {
-      for (let i = 0; i < 64; i++)
+      for (let i = 0; i < 64; i++) {
         for (let j = 0; j < cLength >> 1; j++) encipher(cdata, j << 1, P, S);
+      }
       const result: number[] = [];
 
       for (let i = 0; i < cLength; i++) {
@@ -267,13 +278,14 @@ export const crypt = (
       return result;
     }
 
-    if (!sync)
+    if (!sync) {
       return new Promise((resolve) =>
         // oxlint-disable-next-line no-promise-executor-return
         nextTick(() => {
           void (next() as Promise<number[] | undefined>).then(resolve);
         }),
       );
+    }
   };
 
   if (!sync) return next() as Promise<number[]>;

src/hash.ts

@@ -1,4 +1,4 @@
-/* oxlint-disable unicorn/prefer-code-point */
+// oxlint-disable unicorn/prefer-code-point
 
 import { decodeBase64, encodeBase64 } from "./base64.js";
 import { BCRYPT_SALT_LEN, C_ORIG, GENERATE_SALT_DEFAULT_LOG2_ROUNDS } from "./constant.js";
@@ -12,6 +12,9 @@ import { convertToUFT8Bytes } from "./uft8.js";
  * @param content String to hash
  * @param salt Salt to use
  * @param progressCallback Callback called with the current progress
+ * @param sync Whether to run synchronously
+ *
+ * @returns Resulting hash
  */
 // oxlint-disable-next-line max-statements
 const _hash = (
@@ -93,6 +96,8 @@ const _hash = (
   /**
    * Finishes hashing.
    * @param bytes Byte array
+   *
+   * @returns Resulting hash
    */
   const finish = (bytes: number[]): string =>
     `$2${minor >= "a" ? minor : ""}$${rounds < 10 ? "0" : ""}${rounds}$${encodeBase64(
@@ -101,10 +106,11 @@ const _hash = (
     )}${encodeBase64(bytes, C_ORIG.length * 4 - 1)}`;
 
   // Sync
-  if (!sync)
+  if (!sync) {
     return (
       crypt(passwordBytes, saltBytes, rounds, false, progressCallback) as Promise<number[]>
     ).then((bytes) => finish(bytes));
+  }
 
   return finish(crypt(passwordBytes, saltBytes, rounds, true, progressCallback) as number[]);
 };
@@ -129,6 +135,8 @@ export const hashSync = (
  * @param salt Salt length to generate or salt to use
  * @param progressCallback Callback successively called with the percentage of rounds completed
  *  (0.0 - 1.0), maximally once per `MAX_EXECUTION_TIME = 100` ms.
+ *
+ * @returns Promise resolving to the resulting hash
  */
 export const hash = async (
   contentString: string,

src/salt.ts

@@ -24,6 +24,7 @@ export const genSaltSync = (rounds = GENERATE_SALT_DEFAULT_LOG2_ROUNDS): string
  * Asynchronously generates a salt.
  *
  * @param rounds Number of rounds to use, defaults to 10 if omitted
+ * @returns Promise resolving to the resulting salt
  */
 export const genSalt = (rounds = GENERATE_SALT_DEFAULT_LOG2_ROUNDS): Promise<string> =>
   new Promise((resolve, reject) =>

src/uft8.ts

@@ -1,6 +1,11 @@
-/* oxlint-disable unicorn/prefer-code-point */
+// oxlint-disable unicorn/prefer-code-point
 
-/** Calculates the byte length of a string encoded as UTF8. */
+/**
+ * Calculates the byte length of a string encoded as UTF8.
+ *
+ * @param content String to measure
+ * @returns Byte length
+ */
 export const getUTF8ByteLength = (content: string): number => {
   let charCodePoint = 0;
   let length = 0;
@@ -21,7 +26,12 @@ export const getUTF8ByteLength = (content: string): number => {
   return length;
 };
 
-/** Converts a string to an array of UTF8 bytes. */
+/**
+ * Converts a string to an array of UTF8 bytes.
+ *
+ * @param content String to convert
+ * @returns Byte array
+ */
 export const convertToUFT8Bytes = (content: string): number[] => {
   let offset = 0;
   let c1;