@prairielearn/zod 1.1.0

package/.mocharc.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+  require: ['tsx'],
+};

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @prairielearn/zod
+
+## 1.1.0
+
+### Minor Changes
+
+- fd1ad7a: Add schemas for basic PostgreSQL data types

package/README.md

@@ -0,0 +1,16 @@
+# `@prairielearn/zod`
+
+Useful Zod schemas.
+
+## Usage
+
+### `BooleanFromCheckboxSchema`
+
+```ts
+import { BooleanFromCheckboxSchema } from '@prairielearn/zod';
+
+BooleanFromCheckboxSchema.parse(''); // false
+BooleanFromCheckboxSchema.parse('true'); // true
+BooleanFromCheckboxSchema.parse('1'); // true
+BooleanFromCheckboxSchema.parse('on'); // true
+```

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/**
+ * A Zod schema for a boolean from a single checkbox input in the body
+ * parameters from a form. This will return a boolean with a value of `true` if
+ * the checkbox is checked (the input is present) and `false` if it is not
+ * checked.
+ */
+export declare const BooleanFromCheckboxSchema: z.ZodEffects<z.ZodOptional<z.ZodString>, boolean, string | undefined>;
+/**
+ * A Zod schema for a PostgreSQL ID.
+ *
+ * We store IDs as BIGINT in PostgreSQL, which are passed to JavaScript as
+ * either strings (if the ID is fetched directly) or numbers (if passed via
+ * `to_jsonb()`). This schema coerces the ID to a string to ensure consistent
+ * handling.
+ *
+ * The `refine` step is important to ensure that the thing we've coerced to a
+ * string is actually a number. If it's not, we want to fail quickly.
+ */
+export declare const IdSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * A Zod schema for a PostgreSQL interval.
+ *
+ * This handles two representations of an interval:
+ *
+ * - A string like "1 year 2 days", which is how intervals will be represented
+ *   if they go through `to_jsonb` in a query.
+ * - A {@link PostgresIntervalSchema} object, which is what we'll get if a
+ *   query directly returns an interval column. The interval will already be
+ *   parsed by `postgres-interval` by way of `pg-types`.
+ *
+ * In either case, we convert the interval to a number of milliseconds.
+ */
+export declare const IntervalSchema: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodObject<{
+    years: z.ZodDefault<z.ZodNumber>;
+    months: z.ZodDefault<z.ZodNumber>;
+    days: z.ZodDefault<z.ZodNumber>;
+    hours: z.ZodDefault<z.ZodNumber>;
+    minutes: z.ZodDefault<z.ZodNumber>;
+    seconds: z.ZodDefault<z.ZodNumber>;
+    milliseconds: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}, {
+    years?: number | undefined;
+    months?: number | undefined;
+    days?: number | undefined;
+    hours?: number | undefined;
+    minutes?: number | undefined;
+    seconds?: number | undefined;
+    milliseconds?: number | undefined;
+}>]>, number, string | {
+    years?: number | undefined;
+    months?: number | undefined;
+    days?: number | undefined;
+    hours?: number | undefined;
+    minutes?: number | undefined;
+    seconds?: number | undefined;
+    milliseconds?: number | undefined;
+}>;
+/**
+ * A Zod schema for a date string in ISO format.
+ *
+ * Accepts either a string or a Date object. If a string is passed, it is
+ * validated and parsed as an ISO date string.
+ *
+ * Useful for parsing dates from JSON, which are always strings.
+ */
+export declare const DateFromISOString: z.ZodEffects<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string | Date, string | Date>, Date, string | Date>;

package/dist/index.js

@@ -0,0 +1,93 @@
+import parsePostgresInterval from 'postgres-interval';
+import { z } from 'zod';
+const INTERVAL_MS_PER_SECOND = 1000;
+const INTERVAL_MS_PER_MINUTE = 60 * INTERVAL_MS_PER_SECOND;
+const INTERVAL_MS_PER_HOUR = 60 * INTERVAL_MS_PER_MINUTE;
+const INTERVAL_MS_PER_DAY = 24 * INTERVAL_MS_PER_HOUR;
+const INTERVAL_MS_PER_MONTH = 30 * INTERVAL_MS_PER_DAY;
+const INTERVAL_MS_PER_YEAR = 365.25 * INTERVAL_MS_PER_DAY;
+/**
+ * A Zod schema for a boolean from a single checkbox input in the body
+ * parameters from a form. This will return a boolean with a value of `true` if
+ * the checkbox is checked (the input is present) and `false` if it is not
+ * checked.
+ */
+export const BooleanFromCheckboxSchema = z
+    .string()
+    .optional()
+    .transform((s) => !!s);
+/**
+ * A Zod schema for a PostgreSQL ID.
+ *
+ * We store IDs as BIGINT in PostgreSQL, which are passed to JavaScript as
+ * either strings (if the ID is fetched directly) or numbers (if passed via
+ * `to_jsonb()`). This schema coerces the ID to a string to ensure consistent
+ * handling.
+ *
+ * The `refine` step is important to ensure that the thing we've coerced to a
+ * string is actually a number. If it's not, we want to fail quickly.
+ */
+export const IdSchema = z
+    .string({ coerce: true })
+    .refine((val) => /^\d+$/.test(val), { message: 'ID is not a non-negative integer' });
+/**
+ * A Zod schema for the objects produced by the `postgres-interval` library.
+ */
+const PostgresIntervalSchema = z.object({
+    years: z.number().default(0),
+    months: z.number().default(0),
+    days: z.number().default(0),
+    hours: z.number().default(0),
+    minutes: z.number().default(0),
+    seconds: z.number().default(0),
+    milliseconds: z.number().default(0),
+});
+/**
+ * A Zod schema for a PostgreSQL interval.
+ *
+ * This handles two representations of an interval:
+ *
+ * - A string like "1 year 2 days", which is how intervals will be represented
+ *   if they go through `to_jsonb` in a query.
+ * - A {@link PostgresIntervalSchema} object, which is what we'll get if a
+ *   query directly returns an interval column. The interval will already be
+ *   parsed by `postgres-interval` by way of `pg-types`.
+ *
+ * In either case, we convert the interval to a number of milliseconds.
+ */
+export const IntervalSchema = z
+    .union([z.string(), PostgresIntervalSchema])
+    .transform((interval) => {
+    if (typeof interval === 'string') {
+        interval = parsePostgresInterval(interval);
+    }
+    // This calculation matches Postgres's behavior when computing the number of
+    // milliseconds in an interval with `EXTRACT(epoch from '...'::interval) * 1000`.
+    // The noteworthy parts of this conversion are that 1 year = 365.25 days and
+    // 1 month = 30 days.
+    return (interval.years * INTERVAL_MS_PER_YEAR +
+        interval.months * INTERVAL_MS_PER_MONTH +
+        interval.days * INTERVAL_MS_PER_DAY +
+        interval.hours * INTERVAL_MS_PER_HOUR +
+        interval.minutes * INTERVAL_MS_PER_MINUTE +
+        interval.seconds * INTERVAL_MS_PER_SECOND +
+        interval.milliseconds);
+});
+/**
+ * A Zod schema for a date string in ISO format.
+ *
+ * Accepts either a string or a Date object. If a string is passed, it is
+ * validated and parsed as an ISO date string.
+ *
+ * Useful for parsing dates from JSON, which are always strings.
+ */
+export const DateFromISOString = z
+    .union([z.string(), z.date()])
+    .refine((s) => {
+    const date = new Date(s);
+    return !Number.isNaN(date.getTime());
+}, {
+    message: 'must be a valid ISO date string',
+})
+    .transform((s) => new Date(s));
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import parsePostgresInterval from 'postgres-interval';\nimport { z } from 'zod';\n\nconst INTERVAL_MS_PER_SECOND = 1000;\nconst INTERVAL_MS_PER_MINUTE = 60 * INTERVAL_MS_PER_SECOND;\nconst INTERVAL_MS_PER_HOUR = 60 * INTERVAL_MS_PER_MINUTE;\nconst INTERVAL_MS_PER_DAY = 24 * INTERVAL_MS_PER_HOUR;\nconst INTERVAL_MS_PER_MONTH = 30 * INTERVAL_MS_PER_DAY;\nconst INTERVAL_MS_PER_YEAR = 365.25 * INTERVAL_MS_PER_DAY;\n\n/**\n * A Zod schema for a boolean from a single checkbox input in the body\n * parameters from a form. This will return a boolean with a value of `true` if\n * the checkbox is checked (the input is present) and `false` if it is not\n * checked.\n */\nexport const BooleanFromCheckboxSchema = z\n  .string()\n  .optional()\n  .transform((s) => !!s);\n\n/**\n * A Zod schema for a PostgreSQL ID.\n *\n * We store IDs as BIGINT in PostgreSQL, which are passed to JavaScript as\n * either strings (if the ID is fetched directly) or numbers (if passed via\n * `to_jsonb()`). This schema coerces the ID to a string to ensure consistent\n * handling.\n *\n * The `refine` step is important to ensure that the thing we've coerced to a\n * string is actually a number. If it's not, we want to fail quickly.\n */\nexport const IdSchema = z\n  .string({ coerce: true })\n  .refine((val) => /^\\d+$/.test(val), { message: 'ID is not a non-negative integer' });\n\n/**\n * A Zod schema for the objects produced by the `postgres-interval` library.\n */\nconst PostgresIntervalSchema = z.object({\n  years: z.number().default(0),\n  months: z.number().default(0),\n  days: z.number().default(0),\n  hours: z.number().default(0),\n  minutes: z.number().default(0),\n  seconds: z.number().default(0),\n  milliseconds: z.number().default(0),\n});\n\n/**\n * A Zod schema for a PostgreSQL interval.\n *\n * This handles two representations of an interval:\n *\n * - A string like \"1 year 2 days\", which is how intervals will be represented\n *   if they go through `to_jsonb` in a query.\n * - A {@link PostgresIntervalSchema} object, which is what we'll get if a\n *   query directly returns an interval column. The interval will already be\n *   parsed by `postgres-interval` by way of `pg-types`.\n *\n * In either case, we convert the interval to a number of milliseconds.\n */\nexport const IntervalSchema = z\n  .union([z.string(), PostgresIntervalSchema])\n  .transform((interval) => {\n    if (typeof interval === 'string') {\n      interval = parsePostgresInterval(interval);\n    }\n\n    // This calculation matches Postgres's behavior when computing the number of\n    // milliseconds in an interval with `EXTRACT(epoch from '...'::interval) * 1000`.\n    // The noteworthy parts of this conversion are that 1 year = 365.25 days and\n    // 1 month = 30 days.\n    return (\n      interval.years * INTERVAL_MS_PER_YEAR +\n      interval.months * INTERVAL_MS_PER_MONTH +\n      interval.days * INTERVAL_MS_PER_DAY +\n      interval.hours * INTERVAL_MS_PER_HOUR +\n      interval.minutes * INTERVAL_MS_PER_MINUTE +\n      interval.seconds * INTERVAL_MS_PER_SECOND +\n      interval.milliseconds\n    );\n  });\n\n/**\n * A Zod schema for a date string in ISO format.\n *\n * Accepts either a string or a Date object. If a string is passed, it is\n * validated and parsed as an ISO date string.\n *\n * Useful for parsing dates from JSON, which are always strings.\n */\nexport const DateFromISOString = z\n  .union([z.string(), z.date()])\n  .refine(\n    (s) => {\n      const date = new Date(s);\n      return !Number.isNaN(date.getTime());\n    },\n    {\n      message: 'must be a valid ISO date string',\n    },\n  )\n  .transform((s) => new Date(s));\n"]}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,64 @@
+import { assert } from 'chai';
+import parsePostgresInterval from 'postgres-interval';
+import { IdSchema, IntervalSchema } from './index.js';
+describe('IdSchema', () => {
+    it('parses a valid id', () => {
+        const id = IdSchema.parse('123');
+        assert.equal(id, '123');
+    });
+    it('parses a nullable id', () => {
+        const id = IdSchema.nullable().parse(null);
+        assert.equal(id, null);
+    });
+    it('parses an optional id', () => {
+        const id = IdSchema.optional().parse(undefined);
+        assert.equal(id, undefined);
+    });
+    it('rejects a negative ID', () => {
+        const result = IdSchema.safeParse('-1');
+        assert.isFalse(result.success);
+    });
+    it('rejects a non-numeric ID', () => {
+        const result = IdSchema.safeParse('abc');
+        assert.isFalse(result.success);
+    });
+});
+describe('IntervalSchema', () => {
+    it('handles a PostgresInterval object', () => {
+        const interval = IntervalSchema.parse(parsePostgresInterval('1 year 2 months 3 days'));
+        assert.equal(interval, 37000800000);
+    });
+    it('parses an interval with date', () => {
+        const interval = IntervalSchema.parse('1 year 2 months 3 days');
+        assert.equal(interval, 37000800000);
+    });
+    it('parses an interval with time', () => {
+        const interval = IntervalSchema.parse('04:05:06.7');
+        assert.equal(interval, 14706700);
+    });
+    it('parses an interval with microsecond-precision time', () => {
+        const interval = IntervalSchema.parse('01:02:03.456789');
+        assert.equal(interval, 3723456.789);
+    });
+    it('parses a complex interval', () => {
+        const interval = IntervalSchema.parse('1 years 2 mons 3 days 04:05:06.789');
+        assert.equal(interval, 37015506789);
+    });
+    it('parses interval with negative months', () => {
+        const interval = IntervalSchema.parse('-10 mons 3 days 04:05:06.789');
+        assert.equal(interval, -25646093211);
+    });
+    it('parses interval with negative years and months', () => {
+        const interval = IntervalSchema.parse('-1 years -2 months 3 days 04:05:06.789');
+        assert.equal(interval, -36467693211);
+    });
+    it('parses interval with negative years, months, and days', () => {
+        const interval = IntervalSchema.parse('-1 years -2 months -3 days 04:05:06.789');
+        assert.equal(interval, -36986093211);
+    });
+    it('parses a negative interval', () => {
+        const interval = IntervalSchema.parse('-1 years -2 months -3 days -04:05:06.789');
+        assert.equal(interval, -37015506789);
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { assert } from 'chai';\nimport parsePostgresInterval from 'postgres-interval';\n\nimport { IdSchema, IntervalSchema } from './index.js';\n\ndescribe('IdSchema', () => {\n  it('parses a valid id', () => {\n    const id = IdSchema.parse('123');\n    assert.equal(id, '123');\n  });\n\n  it('parses a nullable id', () => {\n    const id = IdSchema.nullable().parse(null);\n    assert.equal(id, null);\n  });\n\n  it('parses an optional id', () => {\n    const id = IdSchema.optional().parse(undefined);\n    assert.equal(id, undefined);\n  });\n\n  it('rejects a negative ID', () => {\n    const result = IdSchema.safeParse('-1');\n    assert.isFalse(result.success);\n  });\n\n  it('rejects a non-numeric ID', () => {\n    const result = IdSchema.safeParse('abc');\n    assert.isFalse(result.success);\n  });\n});\n\ndescribe('IntervalSchema', () => {\n  it('handles a PostgresInterval object', () => {\n    const interval = IntervalSchema.parse(parsePostgresInterval('1 year 2 months 3 days'));\n    assert.equal(interval, 37000800000);\n  });\n\n  it('parses an interval with date', () => {\n    const interval = IntervalSchema.parse('1 year 2 months 3 days');\n    assert.equal(interval, 37000800000);\n  });\n\n  it('parses an interval with time', () => {\n    const interval = IntervalSchema.parse('04:05:06.7');\n    assert.equal(interval, 14706700);\n  });\n\n  it('parses an interval with microsecond-precision time', () => {\n    const interval = IntervalSchema.parse('01:02:03.456789');\n    assert.equal(interval, 3723456.789);\n  });\n\n  it('parses a complex interval', () => {\n    const interval = IntervalSchema.parse('1 years 2 mons 3 days 04:05:06.789');\n    assert.equal(interval, 37015506789);\n  });\n\n  it('parses interval with negative months', () => {\n    const interval = IntervalSchema.parse('-10 mons 3 days 04:05:06.789');\n    assert.equal(interval, -25646093211);\n  });\n\n  it('parses interval with negative years and months', () => {\n    const interval = IntervalSchema.parse('-1 years -2 months 3 days 04:05:06.789');\n    assert.equal(interval, -36467693211);\n  });\n\n  it('parses interval with negative years, months, and days', () => {\n    const interval = IntervalSchema.parse('-1 years -2 months -3 days 04:05:06.789');\n    assert.equal(interval, -36986093211);\n  });\n\n  it('parses a negative interval', () => {\n    const interval = IntervalSchema.parse('-1 years -2 months -3 days -04:05:06.789');\n    assert.equal(interval, -37015506789);\n  });\n});\n"]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@prairielearn/zod",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrairieLearn/PrairieLearn.git",
+    "directory": "packages/zod"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "test": "c8 mocha src/**/*.test.ts"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "^0.0.0",
+    "@types/chai": "^5.0.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.17.16",
+    "c8": "^10.1.3",
+    "chai": "^5.1.2",
+    "mocha": "^10.8.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "postgres-interval": "^4.0.2",
+    "zod": "^3.24.1"
+  },
+  "c8": {
+    "reporter": [
+      "html",
+      "text-summary",
+      "cobertura"
+    ],
+    "all": true,
+    "include": [
+      "src/**"
+    ]
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,78 @@
+import { assert } from 'chai';
+import parsePostgresInterval from 'postgres-interval';
+
+import { IdSchema, IntervalSchema } from './index.js';
+
+describe('IdSchema', () => {
+  it('parses a valid id', () => {
+    const id = IdSchema.parse('123');
+    assert.equal(id, '123');
+  });
+
+  it('parses a nullable id', () => {
+    const id = IdSchema.nullable().parse(null);
+    assert.equal(id, null);
+  });
+
+  it('parses an optional id', () => {
+    const id = IdSchema.optional().parse(undefined);
+    assert.equal(id, undefined);
+  });
+
+  it('rejects a negative ID', () => {
+    const result = IdSchema.safeParse('-1');
+    assert.isFalse(result.success);
+  });
+
+  it('rejects a non-numeric ID', () => {
+    const result = IdSchema.safeParse('abc');
+    assert.isFalse(result.success);
+  });
+});
+
+describe('IntervalSchema', () => {
+  it('handles a PostgresInterval object', () => {
+    const interval = IntervalSchema.parse(parsePostgresInterval('1 year 2 months 3 days'));
+    assert.equal(interval, 37000800000);
+  });
+
+  it('parses an interval with date', () => {
+    const interval = IntervalSchema.parse('1 year 2 months 3 days');
+    assert.equal(interval, 37000800000);
+  });
+
+  it('parses an interval with time', () => {
+    const interval = IntervalSchema.parse('04:05:06.7');
+    assert.equal(interval, 14706700);
+  });
+
+  it('parses an interval with microsecond-precision time', () => {
+    const interval = IntervalSchema.parse('01:02:03.456789');
+    assert.equal(interval, 3723456.789);
+  });
+
+  it('parses a complex interval', () => {
+    const interval = IntervalSchema.parse('1 years 2 mons 3 days 04:05:06.789');
+    assert.equal(interval, 37015506789);
+  });
+
+  it('parses interval with negative months', () => {
+    const interval = IntervalSchema.parse('-10 mons 3 days 04:05:06.789');
+    assert.equal(interval, -25646093211);
+  });
+
+  it('parses interval with negative years and months', () => {
+    const interval = IntervalSchema.parse('-1 years -2 months 3 days 04:05:06.789');
+    assert.equal(interval, -36467693211);
+  });
+
+  it('parses interval with negative years, months, and days', () => {
+    const interval = IntervalSchema.parse('-1 years -2 months -3 days 04:05:06.789');
+    assert.equal(interval, -36986093211);
+  });
+
+  it('parses a negative interval', () => {
+    const interval = IntervalSchema.parse('-1 years -2 months -3 days -04:05:06.789');
+    assert.equal(interval, -37015506789);
+  });
+});

package/src/index.ts

@@ -0,0 +1,104 @@
+import parsePostgresInterval from 'postgres-interval';
+import { z } from 'zod';
+
+const INTERVAL_MS_PER_SECOND = 1000;
+const INTERVAL_MS_PER_MINUTE = 60 * INTERVAL_MS_PER_SECOND;
+const INTERVAL_MS_PER_HOUR = 60 * INTERVAL_MS_PER_MINUTE;
+const INTERVAL_MS_PER_DAY = 24 * INTERVAL_MS_PER_HOUR;
+const INTERVAL_MS_PER_MONTH = 30 * INTERVAL_MS_PER_DAY;
+const INTERVAL_MS_PER_YEAR = 365.25 * INTERVAL_MS_PER_DAY;
+
+/**
+ * A Zod schema for a boolean from a single checkbox input in the body
+ * parameters from a form. This will return a boolean with a value of `true` if
+ * the checkbox is checked (the input is present) and `false` if it is not
+ * checked.
+ */
+export const BooleanFromCheckboxSchema = z
+  .string()
+  .optional()
+  .transform((s) => !!s);
+
+/**
+ * A Zod schema for a PostgreSQL ID.
+ *
+ * We store IDs as BIGINT in PostgreSQL, which are passed to JavaScript as
+ * either strings (if the ID is fetched directly) or numbers (if passed via
+ * `to_jsonb()`). This schema coerces the ID to a string to ensure consistent
+ * handling.
+ *
+ * The `refine` step is important to ensure that the thing we've coerced to a
+ * string is actually a number. If it's not, we want to fail quickly.
+ */
+export const IdSchema = z
+  .string({ coerce: true })
+  .refine((val) => /^\d+$/.test(val), { message: 'ID is not a non-negative integer' });
+
+/**
+ * A Zod schema for the objects produced by the `postgres-interval` library.
+ */
+const PostgresIntervalSchema = z.object({
+  years: z.number().default(0),
+  months: z.number().default(0),
+  days: z.number().default(0),
+  hours: z.number().default(0),
+  minutes: z.number().default(0),
+  seconds: z.number().default(0),
+  milliseconds: z.number().default(0),
+});
+
+/**
+ * A Zod schema for a PostgreSQL interval.
+ *
+ * This handles two representations of an interval:
+ *
+ * - A string like "1 year 2 days", which is how intervals will be represented
+ *   if they go through `to_jsonb` in a query.
+ * - A {@link PostgresIntervalSchema} object, which is what we'll get if a
+ *   query directly returns an interval column. The interval will already be
+ *   parsed by `postgres-interval` by way of `pg-types`.
+ *
+ * In either case, we convert the interval to a number of milliseconds.
+ */
+export const IntervalSchema = z
+  .union([z.string(), PostgresIntervalSchema])
+  .transform((interval) => {
+    if (typeof interval === 'string') {
+      interval = parsePostgresInterval(interval);
+    }
+
+    // This calculation matches Postgres's behavior when computing the number of
+    // milliseconds in an interval with `EXTRACT(epoch from '...'::interval) * 1000`.
+    // The noteworthy parts of this conversion are that 1 year = 365.25 days and
+    // 1 month = 30 days.
+    return (
+      interval.years * INTERVAL_MS_PER_YEAR +
+      interval.months * INTERVAL_MS_PER_MONTH +
+      interval.days * INTERVAL_MS_PER_DAY +
+      interval.hours * INTERVAL_MS_PER_HOUR +
+      interval.minutes * INTERVAL_MS_PER_MINUTE +
+      interval.seconds * INTERVAL_MS_PER_SECOND +
+      interval.milliseconds
+    );
+  });
+
+/**
+ * A Zod schema for a date string in ISO format.
+ *
+ * Accepts either a string or a Date object. If a string is passed, it is
+ * validated and parsed as an ISO date string.
+ *
+ * Useful for parsing dates from JSON, which are always strings.
+ */
+export const DateFromISOString = z
+  .union([z.string(), z.date()])
+  .refine(
+    (s) => {
+      const date = new Date(s);
+      return !Number.isNaN(date.getTime());
+    },
+    {
+      message: 'must be a valid ISO date string',
+    },
+  )
+  .transform((s) => new Date(s));

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@prairielearn/tsconfig/tsconfig.package.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["mocha", "node"]
+  }
+}