@postxl/utils 0.1.8

package/dist/zod-excel.decoders.js

@@ -0,0 +1,397 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.excelDateNullableDecoder = exports.excelDateDecoder = exports.excelBooleanNullableDecoder = exports.excelBooleanDecoder = exports.excelBooleanStrictDecoder = exports.excelBigIntNullableDecoder = exports.excelBigIntDecoder = exports.excelBigIntStrictDecoder = exports.excelIntNullableDecoder = exports.excelIntDecoder = exports.excelIntStrictDecoder = exports.excelNumberNullableDecoder = exports.excelNumberDecoder = exports.excelNumberStrictDecoder = exports.excelStringNullableDecoder = exports.excelStringDecoder = exports.excelStringStrictDecoder = void 0;
+const zod_1 = __importDefault(require("zod"));
+const types_1 = require("./types");
+/**
+ * Transformer that verifies that the number is an integer
+ */
+const intValidator = (x, ctx) => {
+    if (x % 1 !== 0) {
+        ctx.addIssue({
+            code: zod_1.default.ZodIssueCode.custom,
+            message: `Not an integer: ${x}`,
+        });
+        return zod_1.default.NEVER;
+    }
+    return x;
+};
+/**
+ * Converts any transformer to a nullable transformer, i.e. if the input is
+ * null or undefined, the output will be nullable. Else the original transformer
+ * is applied
+ */
+const nullableTransformer = (transformer) => (x, ctx) => {
+    if (x === null || x === undefined) {
+        return null;
+    }
+    return transformer(x, ctx);
+};
+/**
+ * A decoder that transforms Excel strings to JS strings, also handling numbers and boolean. Will not parse any other type!
+ *
+ * Background: In Excel, entering a number in a cell will automatically convert it to a number -
+ * and xlPort will return it as a number. However, often we want to treat it as a string - this decoder
+ * hence accepts both strings and numbers, and converts numbers to strings.
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll be converted to a string
+ * - If the value is a string, it'll be returned as-is
+ * - If the value is boolean, it'll return 'true' or 'false'
+ *
+ * Any other type will throw an error!
+ */
+exports.excelStringStrictDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.boolean()]).transform((x) => {
+    if (typeof x === 'number') {
+        return x.toString();
+    }
+    if (typeof x === 'boolean') {
+        return x ? 'true' : 'false';
+    }
+    return x;
+});
+/**
+ * A decoder that transforms Excel strings to JS strings, also handling numbers and any other potential type
+ *
+ * Background: In Excel, entering a number in a cell will automatically convert it to a number -
+ * and xlPort will return it as a number. However, often we want to treat it as a string - this decoder
+ * hence accepts both strings and numbers, and converts numbers to strings.
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll be converted to a string
+ * - If the value is a string, it'll be returned as-is
+ * - If the value is boolean, it'll return 'true' or 'false'
+ * - If the value is null or undefined, it'll return an empty string
+ * - If the value is any other type, it'll return an empty string
+ */
+exports.excelStringDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.boolean(), zod_1.default.null(), zod_1.default.undefined(), zod_1.default.any()]).transform((x) => {
+    if (x === null || x === undefined) {
+        return '';
+    }
+    if (typeof x === 'number') {
+        return x.toString();
+    }
+    if (typeof x === 'boolean') {
+        return x ? 'true' : 'false';
+    }
+    if (typeof x === 'string') {
+        return x;
+    }
+    return '';
+});
+/**
+ * A decoder that transforms Excel strings to JS strings, also handling numbers and null
+ *
+ * Background: In Excel, entering a number in a cell will automatically convert it to a number -
+ * and xlPort will return it as a number. However, often we want to treat it as a string - this decoder
+ * hence accepts both strings and numbers, and converts numbers to strings.
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll be converted to a string
+ * - If the value is a string, it'll be returned as-is
+ * - If the value is boolean, it'll return 'true' or 'false'
+ * - If the value is null or undefined, it'll return null
+ * - If the value is any other type, it'll return null
+ */
+exports.excelStringNullableDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.boolean(), zod_1.default.null(), zod_1.default.undefined(), zod_1.default.any()]).transform((x) => {
+    if (x === null || x === undefined) {
+        return null;
+    }
+    if (typeof x === 'number') {
+        return x.toString();
+    }
+    if (typeof x === 'boolean') {
+        return x ? 'true' : 'false';
+    }
+    if (typeof x === 'string') {
+        return x;
+    }
+    return null;
+});
+/**
+ * A decoder that transforms Excel numbers to JS numbers, also handling strings and boolean. Will not parse any other type!
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll be returned as-is
+ * - If the value is a string, it'll try to parse it to a number. Blank strings will be converted to 0. Non-numeric strings will throw an error.
+ * - If the value is boolean, it'll return 1 or 0
+ * - If the value is any other type, it'll throw an error
+ *
+ */
+exports.excelNumberStrictDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.boolean()]).transform((x, ctx) => {
+    if (typeof x === 'string') {
+        if (x.trim() === '') {
+            return 0;
+        }
+        const parsed = parseFloat(x);
+        if (isNaN(parsed)) {
+            ctx.addIssue({
+                code: zod_1.default.ZodIssueCode.custom,
+                message: `Not a number: ${x}`,
+            });
+            return zod_1.default.NEVER;
+        }
+        return parsed;
+    }
+    if (typeof x === 'boolean') {
+        return x ? 1 : 0;
+    }
+    return x;
+});
+/**
+ * A decoder that transforms Excel numbers to JS numbers, also handling strings, boolean and other types.
+ 
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll be returned as-is
+ * - If the value is a string, it'll try to parse it to a number. Blank strings and non-numerical strings will be converted to 0.
+ * - If the value is boolean, it'll return 1 or 0
+ * - If the value is any other type, it'll return 0
+ */
+exports.excelNumberDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.boolean(), zod_1.default.null(), zod_1.default.undefined(), zod_1.default.any()]).transform((x) => {
+    if (typeof x === 'string') {
+        if (x.trim() === '') {
+            return 0;
+        }
+        const parsed = parseFloat(x);
+        if (isNaN(parsed)) {
+            return 0;
+        }
+        return parsed;
+    }
+    if (typeof x === 'boolean') {
+        return x ? 1 : 0;
+    }
+    if (typeof x === 'number') {
+        return x;
+    }
+    return 0;
+});
+/**
+ * A decoder that transforms Excel numbers to JS numbers, also handling strings, boolean and other types.
+ 
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll be returned as-is
+ * - If the value is a string, it'll try to parse it to a number. Blank strings and non-numerical strings will be converted to 0.
+ * - If the value is boolean, it'll return 1 or 0
+ * - If the value is any other type, it'll return null
+ */
+exports.excelNumberNullableDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.null(), zod_1.default.number(), zod_1.default.undefined(), zod_1.default.any()]).transform((x) => {
+    if (typeof x === 'string') {
+        if (x.trim() === '') {
+            return null;
+        }
+        const parsed = parseFloat(x);
+        if (isNaN(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    if (typeof x === 'boolean') {
+        return x ? 1 : 0;
+    }
+    if (typeof x === 'number') {
+        return x;
+    }
+    return null;
+});
+/**
+ * A decoder that transforms Excel numbers to JS integers, also handling strings and boolean. Other types will throw an error.
+ *
+ * If the number is not an integer, an error will be thrown.
+ */
+exports.excelIntStrictDecoder = exports.excelNumberStrictDecoder.transform(intValidator);
+/**
+ * A decoder that transforms Excel numbers to JS integers, also handling strings and boolean. Other types will be converted to 0.
+ *
+ * If the number is not an integer, an error will be thrown.
+ */
+exports.excelIntDecoder = exports.excelNumberDecoder.transform(intValidator);
+/**
+ * A decoder that transforms Excel numbers to JS integers, also handling strings and boolean. Other types will be converted to null.
+ *
+ * If the number is not an integer, an error will be thrown.
+ */
+exports.excelIntNullableDecoder = exports.excelNumberNullableDecoder.transform(nullableTransformer(intValidator));
+// TODO: Add BigInt tests (to be investigated, how Excel handles BigInts)
+const bigIntTransformer = (x, ctx) => {
+    if (x % 1 !== 0) {
+        ctx.addIssue({
+            code: zod_1.default.ZodIssueCode.custom,
+            message: `Not an integer: ${x}`,
+        });
+        return zod_1.default.NEVER;
+    }
+    return BigInt(x);
+};
+/**
+ * A decoder that transforms Excel numbers to JS BigInts, also handling strings and boolean. Other types will throw an error.
+ *
+ * If the number is not a (big) integer, an error will be thrown.
+ */
+exports.excelBigIntStrictDecoder = exports.excelNumberStrictDecoder.transform(bigIntTransformer);
+/**
+ * A decoder that transforms Excel numbers to JS BigInts, also handling strings and boolean. Other types will be converted to 0.
+ *
+ * If the number is not a (big) integer, an error will be thrown.
+ */
+exports.excelBigIntDecoder = exports.excelNumberDecoder.transform(bigIntTransformer);
+/**
+ * A decoder that transforms Excel numbers to JS BigInts, also handling strings and boolean. Other types will be converted to null.
+ *
+ * If the number is not a (big) integer, an error will be thrown.
+ */
+exports.excelBigIntNullableDecoder = exports.excelNumberNullableDecoder.transform(nullableTransformer(bigIntTransformer));
+/**
+ * A decoder that transforms Excel booleans to JS booleans, also handling numbers and strings.
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll return true if it's not 0
+ * - If the value is a string, it'll return true if it's 'true' or '1', false if it's 'false' or '0', and throw an error otherwise
+ * - If the value is boolean, it'll return it as-is
+ * - If the value is any other type, it'll throw an error
+ */
+exports.excelBooleanStrictDecoder = zod_1.default.union([zod_1.default.boolean(), zod_1.default.number(), zod_1.default.string()]).transform((x, ctx) => {
+    if (typeof x === 'number') {
+        return x !== 0;
+    }
+    if (typeof x === 'string') {
+        switch (x.toLowerCase()) {
+            case 'true':
+            case '1':
+                return true;
+            case 'false':
+            case '0':
+                return false;
+            default:
+                ctx.addIssue({
+                    code: zod_1.default.ZodIssueCode.custom,
+                    message: `Not a boolean: ${x}`,
+                });
+                return zod_1.default.NEVER;
+        }
+    }
+    if (typeof x === 'boolean') {
+        return x;
+    }
+    throw new types_1.ExhaustiveSwitchCheck(x);
+});
+/**
+ * A decoder that transforms Excel booleans to JS booleans, also handling numbers and strings.
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll return true if it's not 0
+ * - If the value is a string, it'll return true if it's 'true' or '1', false otherwise
+ * - If the value is boolean, it'll return it as-is
+ * - If the value is any other type, it'll return false
+ */
+exports.excelBooleanDecoder = zod_1.default.union([zod_1.default.boolean(), zod_1.default.number(), zod_1.default.null(), zod_1.default.string(), zod_1.default.undefined(), zod_1.default.any()]).transform((x) => {
+    if (typeof x === 'number') {
+        return x !== 0;
+    }
+    if (typeof x === 'string') {
+        switch (x.toLowerCase()) {
+            case 'true':
+            case '1':
+                return true;
+            case 'false':
+            case '0':
+                return false;
+            default:
+                return false;
+        }
+    }
+    if (typeof x === 'boolean') {
+        return x;
+    }
+    return false;
+});
+/**
+ * A decoder that transforms Excel booleans to JS booleans, also handling numbers and strings.
+ *
+ * It'll perform casting based on the following rules:
+ * - If the value is a number, it'll return true if it's not 0
+ * - If the value is a string, it'll return true if it's 'true' or '1', false if it's 'false' or '0', and null otherwise
+ * - If the value is boolean, it'll return it as-is
+ * - If the value is any other type, it'll return null
+ */
+exports.excelBooleanNullableDecoder = zod_1.default.union([zod_1.default.boolean(), zod_1.default.number(), zod_1.default.null(), zod_1.default.string(), zod_1.default.undefined(), zod_1.default.any()]).transform((x) => {
+    if (typeof x === 'number') {
+        return x !== 0;
+    }
+    if (typeof x === 'string') {
+        switch (x.toLowerCase()) {
+            case 'true':
+            case '1':
+                return true;
+            case 'false':
+            case '0':
+                return false;
+            default:
+                return null;
+        }
+    }
+    if (typeof x === 'boolean') {
+        return x;
+    }
+    return null;
+});
+/**
+ * A decoder that transforms Excel dates to JS Dates
+ */
+exports.excelDateDecoder = zod_1.default
+    .union([zod_1.default.number(), zod_1.default.string()])
+    .transform((x, ctx) => {
+    if (typeof x === 'number') {
+        // Excel number is a float with 1 representing Jan 1, 1900. Each increment is a day.
+        // As Excel incorrectly ignores the 1900 leap year, we need to correct for that
+        const date = new Date(Date.UTC(1900, 0, 1));
+        date.setDate(date.getDate() + x - 2);
+        const fractionalDay = x - Math.floor(x);
+        date.setMilliseconds(date.getMilliseconds() + fractionalDay * 24 * 60 * 60 * 1000);
+        return date;
+    }
+    const result = new Date(x);
+    if (isNaN(result.getTime())) {
+        ctx.addIssue({
+            code: zod_1.default.ZodIssueCode.custom,
+            message: `Not a date: ${x}`,
+        });
+        return zod_1.default.NEVER;
+    }
+    return result;
+});
+/**
+ * A decoder that transforms nullable Excel dates to JS Dates
+ */
+exports.excelDateNullableDecoder = zod_1.default.union([zod_1.default.string(), zod_1.default.number(), zod_1.default.null(), zod_1.default.undefined(), zod_1.default.any()]).transform((x, ctx) => {
+    if (x === null || x === undefined) {
+        return null;
+    }
+    if (typeof x === 'number') {
+        // Excel number is a float with 1 representing Jan 1, 1900. Each increment is a day.
+        // As Excel incorrectly ignores the 1900 leap year, we need to correct for that
+        const date = new Date(Date.UTC(1900, 0, 1));
+        date.setDate(date.getDate() + x - 2);
+        const fractionalDay = x - Math.floor(x);
+        date.setMilliseconds(date.getMilliseconds() + fractionalDay * 24 * 60 * 60 * 1000);
+        return date;
+    }
+    if (typeof x === 'string') {
+        if (x.trim() === '') {
+            return null;
+        }
+        const result = new Date(x);
+        if (isNaN(result.getTime())) {
+            ctx.addIssue({
+                code: zod_1.default.ZodIssueCode.custom,
+                message: `Not a date: ${x}`,
+            });
+            return zod_1.default.NEVER;
+        }
+        return result;
+    }
+    return null;
+});

package/dist/zod.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export type Transformer<Input, Output> = (value: Input, ctx: z.RefinementCtx) => Output | z.ZodNever;
+type ReturnTypeOfLast<T extends any[]> = T extends [...any, infer L] ? L extends (...args: any) => any ? ReturnType<L> : never : never;
+/**
+ * Pipes a list of Zod transformers together in a type-safe way. Returns early if any of the transformers returns `z.NEVER`.
+ */
+export declare function pipeZodTransformers<Initial, Fns extends [Transformer<any, any>, ...Transformer<any, any>[]]>(initialValue: Initial, ctx: z.RefinementCtx, fns: Fns): ReturnTypeOfLast<Fns>;
+export {};

package/dist/zod.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pipeZodTransformers = pipeZodTransformers;
+const zod_1 = require("zod");
+/**
+ * Pipes a list of Zod transformers together in a type-safe way. Returns early if any of the transformers returns `z.NEVER`.
+ */
+function pipeZodTransformers(initialValue, ctx, fns) {
+    let result = initialValue;
+    for (const fn of fns) {
+        result = fn(result, ctx);
+        if (result === zod_1.z.NEVER) {
+            return zod_1.z.NEVER;
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@postxl/utils",
+  "version": "0.1.8",
+  "main": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "lint": "eslint .",
+    "prettier:check": "prettier --check \"**/*.{ts,tsx}\" --config ../../prettier.config.js",
+    "test:jest": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:types": "tsc --noEmit",
+    "watch": "tsc -b tsconfig.build.json -w"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "3.24.1"
+  },
+  "devDependencies": {
+    "tsconfig-paths": "4.2.0"
+  },
+  "wallaby": {
+    "env": {
+      "type": "node",
+      "params": {
+        "runner": "--experimental-vm-modules"
+      }
+    }
+  }
+}