chore: migrate to zod for parsing

Author: jamiebrynes7

plugin/package-lock.json

@@ -25,6 +25,7 @@
     "snakify-ts": "^2.3.0",
     "tslib": "^2.4.1",
     "yaml": "^2.1.3",
+    "zod": "^3.24.1",
     "zustand": "^4.5.2"
   },
   "devDependencies": {
@@ -43,4 +44,4 @@
     "vite-tsconfig-paths": "^4.3.2",
     "vitest": "^1.2.2"
   }
-}
+}

plugin/package.json

@@ -1,13 +1,16 @@
 import { t } from "@/i18n";
 import { GroupVariant, type Query, ShowMetadataVariant, SortingVariant } from "@/query/query";
 import YAML from "yaml";
+import { z } from "zod";
 
 export class ParsingError extends Error {
+  messages: string[];
   inner: unknown | undefined;
 
-  constructor(msg: string, inner: unknown | undefined = undefined) {
-    super(msg);
+  constructor(msgs: string[], inner: unknown | undefined = undefined) {
+    super(msgs.join("\n"));
     this.inner = inner;
+    this.messages = msgs;
   }
 
   public toString(): string {
@@ -22,7 +25,7 @@ export class ParsingError extends Error {
 export type QueryWarning = string;
 
 export function parseQuery(raw: string): [Query, QueryWarning[]] {
-  let obj: Record<string, unknown>;
+  let obj: Record<string, unknown> | null = null;
   const warnings: QueryWarning[] = [];
 
   try {
@@ -32,11 +35,15 @@ export function parseQuery(raw: string): [Query, QueryWarning[]] {
     try {
       obj = tryParseAsYaml(raw);
     } catch (e) {
-      throw new ParsingError("Unable to parse as YAML or JSON");
+      throw new ParsingError(["Unable to parse as YAML or JSON"]);
     }
   }
 
-  const [query, parsingWarnings] = parseObject(obj);
+  if (obj === null) {
+    obj = {};
+  }
+
+  const [query, parsingWarnings] = parseObjectZod(obj);
   warnings.push(...parsingWarnings);
 
   return [query, warnings];
@@ -46,169 +53,25 @@ function tryParseAsJson(raw: string): Record<string, unknown> {
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new ParsingError("Invalid JSON", e);
+    throw new ParsingError(["Invalid JSON"], e);
   }
 }
 
 function tryParseAsYaml(raw: string): Record<string, unknown> {
   try {
     return YAML.parse(raw);
   } catch (e) {
-    throw new ParsingError("Invalid YAML", e);
-  }
-}
-
-const validQueryKeys = new Set(["name", "filter", "autorefresh", "sorting", "show", "groupBy"]);
-
-function parseObject(query: Record<string, unknown>): [Query, QueryWarning[]] {
-  const warnings: QueryWarning[] = [];
-
-  for (const key of Object.keys(query)) {
-    if (!validQueryKeys.has(key)) {
-      warnings.push(t().query.warning.unknownKey(key));
-    }
-  }
-
-  return [
-    {
-      name: stringField(query, "name") ?? "",
-      filter: asRequired("filter", stringField(query, "filter")),
-      autorefresh: numberField(query, "autorefresh", { isPositive: true }) ?? 0,
-      sorting: optionsArrayField(query, "sorting", sortingLookup) ?? [SortingVariant.Order],
-      show: new Set(
-        optionsArrayField(query, "show", showMetadataVariantLookup) ??
-          Object.values(showMetadataVariantLookup),
-      ),
-      groupBy: optionField(query, "groupBy", groupByVariantLookup) ?? GroupVariant.None,
-    },
-    warnings,
-  ];
-}
-
-function asRequired<T>(key: string, val: T | undefined): T {
-  if (val === undefined) {
-    throw new ParsingError(`Field ${key} must be text`);
-  }
-
-  return val as T;
-}
-
-function stringField(obj: Record<string, unknown>, key: string): string | undefined {
-  const value = obj[key];
-
-  if (value === undefined) {
-    return undefined;
-  }
-
-  if (typeof value !== "string") {
-    throw new ParsingError(`Field ${key} must be text`);
-  }
-
-  return value as string;
-}
-
-function numberField(
-  obj: Record<string, unknown>,
-  key: string,
-  options?: { isPositive: boolean },
-): number | undefined {
-  const value = obj[key];
-
-  if (value === undefined) {
-    return undefined;
-  }
-
-  if (typeof value !== "number") {
-    throw new ParsingError(`Field ${key} must be a number`);
-  }
-
-  const num = value as number;
-
-  if (Number.isNaN(num)) {
-    throw new ParsingError(`Field ${key} must be a number`);
-  }
-
-  if ((options?.isPositive ?? false) && num < 0) {
-    throw new ParsingError(`Field ${key} must be a positive number`);
-  }
-
-  return num;
-}
-
-function booleanField(obj: Record<string, unknown>, key: string): boolean | undefined {
-  const value = obj[key];
-
-  if (value === undefined) {
-    return undefined;
-  }
-
-  if (typeof value !== "boolean") {
-    throw new ParsingError(`Field ${key} must be a boolean.`);
+    throw new ParsingError(["Invalid YAML"], e);
   }
-
-  return value as boolean;
 }
 
-function optionsArrayField<T>(
-  obj: Record<string, unknown>,
-  key: string,
-  lookup: Record<string, T>,
-): T[] | undefined {
-  const value = obj[key];
-
-  if (value === undefined) {
-    return undefined;
-  }
-
-  const opts = Object.keys(lookup).join(", ");
-  if (!Array.isArray(value)) {
-    throw new ParsingError(`Field ${key} must be an array from values: ${opts}`);
-  }
-
-  const elems = value as Record<string, unknown>[];
-  const parsedElems = [];
-
-  for (const ele of elems) {
-    if (typeof ele !== "string") {
-      throw new ParsingError(`Field ${key} must be an array from values: ${opts}`);
-    }
-
-    const lookupValue = lookup[ele];
-    if (lookupValue === undefined) {
-      throw new ParsingError(`Field ${key} must be an array from values: ${opts}`);
-    }
-
-    parsedElems.push(lookupValue);
-  }
-
-  return parsedElems;
-}
-
-function optionField<T>(
-  obj: Record<string, unknown>,
-  key: string,
-  lookup: Record<string, T>,
-): T | undefined {
-  const value = obj[key];
-
-  if (value === undefined) {
-    return undefined;
-  }
-
-  const opts = Object.keys(lookup).join(", ");
-  if (typeof value !== "string") {
-    throw new ParsingError(`Field ${key} must be one of: ${opts}`);
-  }
-
-  const lookupValue = lookup[value];
-  if (lookupValue === undefined) {
-    throw new ParsingError(`Field ${key} must be one of: ${opts}`);
-  }
-
-  return lookupValue;
-}
+const lookupToEnum = <T>(lookup: Record<string, T>) => {
+  const keys = Object.keys(lookup);
+  //@ts-ignore: There is at least one element for these.
+  return z.enum(keys).transform((key) => lookup[key]);
+};
 
-const sortingLookup: Record<string, SortingVariant> = {
+const sortingSchema = lookupToEnum({
   priority: SortingVariant.Priority,
   priorityAscending: SortingVariant.PriorityAscending,
   priorityDescending: SortingVariant.Priority,
@@ -219,21 +82,93 @@ const sortingLookup: Record<string, SortingVariant> = {
   dateAdded: SortingVariant.DateAdded,
   dateAddedAscending: SortingVariant.DateAdded,
   dateAddedDescending: SortingVariant.DateAddedDescending,
-};
+});
 
-const showMetadataVariantLookup: Record<string, ShowMetadataVariant> = {
+const showSchema = lookupToEnum({
   due: ShowMetadataVariant.Due,
   date: ShowMetadataVariant.Due,
   description: ShowMetadataVariant.Description,
   labels: ShowMetadataVariant.Labels,
   project: ShowMetadataVariant.Project,
-};
+});
 
-const groupByVariantLookup: Record<string, GroupVariant> = {
+const groupBySchema = lookupToEnum({
   project: GroupVariant.Project,
   section: GroupVariant.Section,
   priority: GroupVariant.Priority,
   due: GroupVariant.Date,
   date: GroupVariant.Date,
   labels: GroupVariant.Label,
+});
+
+const defaults = {
+  name: "",
+  autorefresh: 0,
+  sorting: [SortingVariant.Order],
+  show: [
+    ShowMetadataVariant.Due,
+    ShowMetadataVariant.Description,
+    ShowMetadataVariant.Labels,
+    ShowMetadataVariant.Project,
+  ],
+  groupBy: GroupVariant.None,
 };
+
+const querySchema = z.object({
+  name: z.string().optional().default(""),
+  filter: z.string(),
+  autorefresh: z.number().nonnegative().optional().default(0),
+  sorting: z
+    .array(sortingSchema)
+    .optional()
+    .transform((val) => val ?? defaults.sorting),
+  show: z
+    .array(showSchema)
+    .optional()
+    .transform((val) => val ?? defaults.show),
+  groupBy: groupBySchema.optional().transform((val) => val ?? defaults.groupBy),
+});
+
+const validQueryKeys: string[] = querySchema.keyof().options;
+
+function parseObjectZod(query: Record<string, unknown>): [Query, QueryWarning[]] {
+  const warnings: QueryWarning[] = [];
+
+  for (const key of Object.keys(query)) {
+    if (!validQueryKeys.includes(key)) {
+      warnings.push(t().query.warning.unknownKey(key));
+    }
+  }
+
+  const out = querySchema.safeParse(query);
+
+  if (!out.success) {
+    throw new ParsingError(formatZodError(out.error));
+  }
+
+  return [
+    {
+      name: out.data.name,
+      filter: out.data.filter,
+      autorefresh: out.data.autorefresh,
+      sorting: out.data.sorting,
+      show: new Set(out.data.show),
+      groupBy: out.data.groupBy,
+    },
+    warnings,
+  ];
+}
+
+function formatZodError(error: z.ZodError): string[] {
+  return error.errors.map((err) => {
+    const field = err.path[0];
+    switch (err.code) {
+      case "invalid_type":
+        return `Field '${field}' is ${err.received === "undefined" ? "required" : `must be a ${err.expected}`}`;
+      case "invalid_enum_value":
+        return `Field '${field}' has invalid value '${err.received}'. Valid options are: ${err.options?.join(", ")}`;
+      default:
+        return `Field '${field}': ${err.message}`;
+    }
+  });
+}

plugin/src/query/parser.ts

@@ -1,4 +1,5 @@
 import { t } from "@/i18n";
+import { ParsingError } from "@/query/parser";
 import { Callout } from "@/ui/components/callout";
 import type React from "react";
 
@@ -14,14 +15,18 @@ export const QueryError: React.FC<Props> = ({ error }) => {
       className="todoist-query-error"
       title={i18n.header}
       iconId="lucide-alert-triangle"
-      contents={[getErrorMessage(error) ?? i18n.unknownErrorMessage]}
+      contents={getErrorMessages(error) ?? [i18n.unknownErrorMessage]}
     />
   );
 };
 
-const getErrorMessage = (error: unknown): string | undefined => {
+const getErrorMessages = (error: unknown): string[] | undefined => {
+  if (error instanceof ParsingError) {
+    return error.messages;
+  }
+
   if (error instanceof Error) {
-    return error.message;
+    return [error.message];
   }
 
   return;