@thejob/schema 2.1.8 → 2.2.0

package/src/common/facet.schema.ts

@@ -0,0 +1,342 @@
+/**
+ * Reusable builders for FILTER FACETS, shared by every filter schema.
+ *
+ * These describe the SHAPE a facet takes, not what it means: a token list, a
+ * closed enum list, a relative window in days. Nothing here knows about users,
+ * jobs or groups, which is why they live in `common/` rather than beside the
+ * first filter that happened to need them.
+ *
+ * Two conventions are load-bearing and easy to undo by accident:
+ *
+ *   • LIST facets `.default([])`, so a validated filter always has a concrete
+ *     array and a consumer never writes `?? []`.
+ *   • SCALAR facets `.default(undefined)`, NOT 0. "Unset" and "zero" are
+ *     different questions — `days(0)` means "today", and defaulting to 0 would
+ *     turn an absent window into a filter that matches almost nobody.
+ *
+ * A facet that a filter declares but a service does not accept is a 400 on a
+ * request that validated cleanly where it was built, so filter schemas are the
+ * single declaration services derive their vocabulary from rather than restate.
+ */
+import { array, boolean, number, object, string } from "yup";
+
+/**
+ * An open vocabulary: skills, companies, institutes. Any token matches (OR
+ * within a facet); facets AND together.
+ */
+export const tokens = (label: string) =>
+  array().of(string().trim().required()).optional().default([]).label(label);
+
+/**
+ * An open vocabulary of CODES, normalised to uppercase.
+ *
+ * For short closed-ish codes stored uppercase (ISO country, state). The
+ * service matches these case-insensitively anyway, so this is belt-and-braces
+ * — but a filter that reads back `["in"]` after saving looks broken to an
+ * admin, and any consumer comparing the saved value to a stored one would be
+ * comparing "in" against "IN".
+ */
+export const codeTokens = (label: string) =>
+  array()
+    .of(string().trim().uppercase().required())
+    .optional()
+    .default([])
+    .label(label);
+
+/** A closed vocabulary, rendered as a chip picker. */
+export const enumFacet = (values: readonly string[], label: string) =>
+  array()
+    .of(string().oneOf(values).required())
+    .optional()
+    .default([])
+    .label(label);
+
+/**
+ * A relative window in whole days, resolved to an absolute bound at query time.
+ *
+ * Relative rather than absolute because a saved filter is re-resolved on every
+ * run: "within 30 days" keeps meaning what its author intended, while a stored
+ * timestamp rots. Bounded so a typo cannot become an unbounded scan.
+ */
+export const days = (label: string) =>
+  number().integer().min(0).max(3650).optional().default(undefined).label(label);
+
+/** A relative window in whole months. See `days`. */
+export const months = (label: string) =>
+  number().integer().min(0).max(1200).optional().default(undefined).label(label);
+
+/** A 0-100 percentage bound. */
+export const percent = (label: string) =>
+  number().integer().min(0).max(100).optional().default(undefined).label(label);
+
+/**
+ * Absolute epoch milliseconds.
+ *
+ * `widget: "date"` because the STORED form and the ENTERED form are not the
+ * same thing. Epoch ms is right for storage and comparison — `createdAt` is an
+ * integer, and a coerced date string would not compare — but it is not
+ * something anyone types. Rendered as a plain number box, "8" is accepted and
+ * silently means 8ms after 1 Jan 1970, so a filter meant to say "this week"
+ * matches every record ever created and looks correctly configured doing it.
+ *
+ * The form converts; the wire format does not change.
+ */
+export const epoch = (label: string) =>
+  number()
+    .integer()
+    .min(0)
+    .optional()
+    .default(undefined)
+    .label(label)
+    .meta({ widget: "date" });
+
+/**
+ * A money bound that is only meaningful once the filter pins ONE currency.
+ *
+ * Salary is stored as a bare integer with the currency in a separate field, so
+ * "at least 50000" across USD/EUR/GBP/SEK/INR is not a comparison at all — it
+ * silently ranks a Swedish krona salary against a US dollar one. Rather than
+ * return a wrong set, the bound is rejected unless exactly one currency is
+ * selected.
+ *
+ * `currencyField` is a PARAMETER because the sibling facet is named differently
+ * per resource: a user filter pins `salaryCurrencies` against the salary a
+ * candidate wants, while a job filter pins its own currency facet against the
+ * band a job advertises. Hardcoding one name would make this builder silently
+ * inert everywhere else — the `.when` would watch a field that does not exist,
+ * the test would never run, and cross-currency bounds would sail through.
+ */
+export const currencyBound = (label: string, currencyField: string) =>
+  number()
+    .integer()
+    .min(0)
+    .optional()
+    .default(undefined)
+    .label(label)
+    .when(currencyField, {
+      is: (v: unknown) => !Array.isArray(v) || v.length !== 1,
+      then: (s) =>
+        s.test(
+          "requires-single-currency",
+          "Pick exactly one salary currency to filter by salary",
+          (value) => value === undefined || value === null,
+        ),
+    });
+
+/**
+ * A facet over an array of OBJECTS, where the parts must describe the SAME entry.
+ *
+ * The problem this solves, measured on production users:
+ *
+ *   skills[]=python & skillProficiencyLevels[]=expert   ->   301 users
+ *   one skill entry that is BOTH python AND expert      ->   103 users
+ *
+ * Those 198 extra people are expert at something else and happen to also list
+ * Python. As two independent facets the query is `{'skills.name': python,
+ * 'skills.proficiencyLevel': expert}`, and Mongo satisfies each from a
+ * DIFFERENT array entry. English + expert over-counted by 1,755 the same way.
+ *
+ * It is silent: the count is plausible, the filter reads correctly, and the
+ * only symptom is mail reaching people who do not match what the admin chose.
+ *
+ * So the pair is ONE facet with the qualifier nested inside it, not two facets
+ * that a caller is trusted to combine. A single value cannot express the wrong
+ * query, which is the same reason `currencyBound` refuses a bound without
+ * exactly one currency: if a combination is only meaningful together, the
+ * schema should make the meaningless form unsayable rather than answer it
+ * wrongly.
+ *
+ * Each entry is `{ name, <qualifier> }`, where `name` is required (a qualifier
+ * alone means "expert at anything", which is not a segment anyone wants) and
+ * the qualifier is optional (naming the skill without a level is a perfectly
+ * good filter). Entries OR together, matching every other list facet.
+ */
+export const qualified = (
+  qualifierValues: readonly string[] | "open",
+  qualifierKey: string,
+  label: string,
+) =>
+  array()
+    .of(
+      // `rejectUnknownKeys`, not `.noUnknown()`, for the reason spelled out on
+      // that helper: outside strict mode `.noUnknown()` silently STRIPS an
+      // unknown key rather than failing, so a misspelled qualifier would arrive
+      // as a name-only entry and quietly widen the match instead of erroring.
+      rejectUnknownKeys(
+        object({
+          name: string().trim().required().label("Name"),
+          // `"open"` for a free-text qualifier (a certification's issuing body).
+          // An empty array would NOT mean "anything goes" — `.oneOf([])` rejects
+          // every value — so the open case is named rather than inferred from an
+          // empty vocabulary.
+          [qualifierKey]:
+            qualifierValues === "open"
+              ? string().trim().optional().default(undefined).label(label)
+              : string()
+                  .oneOf(qualifierValues)
+                  .optional()
+                  .default(undefined)
+                  .label(label),
+        })
+          .label(label)
+          .required(),
+        () => ["name", qualifierKey],
+      ),
+    )
+    .optional()
+    .default([])
+    .label(label);
+
+/**
+ * A facet over an array of objects where SEVERAL fields describe one entry and
+ * none of them is "the name" the others qualify.
+ *
+ * `qualified` above covers `{ name, <qualifier> }`, where the qualifier is
+ * meaningless alone ("expert" at nothing). This covers the other shape: one
+ * work-history entry is a company AND a job title, one education entry is an
+ * institute AND a course AND a field of study, and each part is a perfectly
+ * good filter on its own.
+ *
+ * That is why the flat `companies` / `designations` facets REMAIN beside this
+ * one rather than being replaced. "Worked at Google" and "was an engineer,
+ * somewhere" are real questions, and an admin asking for both usually does mean
+ * "has each of these somewhere in their history". What was missing is the
+ * narrower question — "was an engineer AT Google" — which as two flat facets
+ * silently also matched someone who was an engineer at Acme and a designer at
+ * Google. Measured on production: VIT + B.Tech returned 71 users where 64 had
+ * one education entry that was both.
+ *
+ * So this ADDS a way to say the precise thing; it does not take away the loose
+ * one. Every field is optional, but an entry must carry at least one — an
+ * all-empty entry would match every row and silently widen the audience, which
+ * is the failure this whole family of facets exists to prevent. Entries OR
+ * together, like every other list facet.
+ *
+ * ── Field types ─────────────────────────────────────────────────────────────
+ * A field is text by default. Pass an object to type it instead:
+ *
+ *   conjunction(["company", "designation", { name: "isCurrent", type: "boolean" }], …)
+ *
+ * The typed forms exist because not every part of an entry is free text. A work
+ * entry is also "is this their CURRENT job" (`duration.isActive`) and "was it
+ * remote" (`isRemote`), and an education entry has a `studyType` from a closed
+ * vocabulary. Those are the parts that make a same-entry filter worth asking:
+ * "engineer at Google" is a different question from "engineer at Google NOW".
+ *
+ * A boolean field is only a constraint when present. `false` is a real value
+ * here ("not their current job"), so it is NOT dropped as empty the way a blank
+ * string is — which is also why a boolean alone satisfies "at least one field".
+ */
+type ConjunctionField =
+  | string
+  | { name: string; type: "string" | "boolean"; oneOf?: readonly string[] };
+
+const conjunctionFieldName = (f: ConjunctionField): string =>
+  typeof f === "string" ? f : f.name;
+
+export const conjunction = (
+  fields: readonly ConjunctionField[],
+  label: string,
+) => {
+  const names = fields.map(conjunctionFieldName);
+  const isBoolean = (name: string) =>
+    fields.some(
+      (f) => typeof f !== "string" && f.name === name && f.type === "boolean",
+    );
+
+  return array()
+    .of(
+      rejectUnknownKeys(
+        object(
+          Object.fromEntries(
+            fields.map((f) => {
+              const name = conjunctionFieldName(f);
+              if (typeof f !== "string" && f.type === "boolean") {
+                return [name, boolean().optional().default(undefined).label(name)];
+              }
+              const base = string().trim().optional().default(undefined).label(name);
+              return [
+                name,
+                typeof f !== "string" && f.oneOf ? base.oneOf([...f.oneOf, undefined]) : base,
+              ];
+            }),
+          ),
+        )
+          .test(
+            "at-least-one-field",
+            // Names the unknown key when that is the real problem. A misspelled
+            // field (`companyName`) is stripped before this test sees it, so it
+            // would otherwise report "needs at least one field set" — true, but
+            // it sends the reader looking in the wrong place.
+            ({ value }) => {
+              const unknown = Object.keys(
+                (value ?? {}) as Record<string, unknown>,
+              ).filter((k) => !names.includes(k));
+              return unknown.length
+                ? `${label} has unsupported keys: ${unknown.join(", ")}`
+                : `${label} needs at least one of: ${names.join(", ")}`;
+            },
+            (value) =>
+              value == null ||
+              names.some((f) => {
+                const v = (value as Record<string, unknown>)[f];
+                // A boolean counts when PRESENT: `false` is the constraint
+                // "not current", not an empty field.
+                if (isBoolean(f)) return typeof v === "boolean";
+                return typeof v === "string" && v.trim() !== "";
+              }),
+          )
+          .label(label)
+          .required(),
+        () => names,
+      ),
+    )
+    .optional()
+    .default([])
+    .label(label);
+};
+
+/**
+ * Reject keys a schema does not declare, WITHOUT turning on strict mode.
+ *
+ * A silently dropped key is the dangerous failure: a filter whose "Has Resume"
+ * checkbox arrives under a misspelled name is not a narrower query, it is the
+ * unfiltered one, and it mails everyone while looking correctly configured. The
+ * caller sees a plausible result and no error, so the mistake survives review.
+ *
+ * Yup's own `.noUnknown()` only ERRORS under `.strict()`, and strict mode also
+ * disables coercion — which would reject the `"80"` and `"true"` strings that
+ * HTML form payloads legitimately send. This is written as a `.test()` instead
+ * so both hold at once: unknown keys fail, coercion stays on.
+ *
+ * `allowed` is a FUNCTION, not an array, for two reasons: it is evaluated at
+ * validation time rather than module-load time (so a schema may reference keys
+ * declared later in the file), and it lets two schemas built from the same shape
+ * permit different key sets — which is how a filter's `or` branch forbids a
+ * nested `or` while the top-level filter allows one.
+ */
+export const rejectUnknownKeys = <T extends { test: (...a: never[]) => T }>(
+  schema: T,
+  allowed: () => readonly string[],
+): T =>
+  (schema.test as unknown as (
+    name: string,
+    msg: (p: { value: unknown; label: string }) => string,
+    fn: (v: unknown) => boolean,
+  ) => T)(
+    "no-unknown-keys",
+    ({ value, label }) => {
+      const known = new Set(allowed());
+      const bad = Object.keys((value ?? {}) as Record<string, unknown>).filter(
+        (k) => !known.has(k),
+      );
+      return `${label} has unsupported keys: ${bad.join(", ")}`;
+    },
+    (value) => {
+      if (value == null) return true;
+      const known = new Set(allowed());
+      return Object.keys(value as Record<string, unknown>).every((k) =>
+        known.has(k),
+      );
+    },
+  );

package/src/feedback/feedback-filter.schema.ts

@@ -0,0 +1,39 @@
+/**
+ * The feedback filter: the closed vocabulary of facets the admin inbox can
+ * filter on, for common-service's `GET /feedback`.
+ *
+ * The counterpart of `PageFilterSchema` and `GroupFilterSchema`. This route had
+ * no declaration at all: it read `filter[type]` and `type` by hand, checked the
+ * value against the enum inline, and SILENTLY DROPPED anything that failed. So
+ * a typo'd or renamed status did not narrow the inbox and did not error — it
+ * returned the whole unfiltered inbox, which looks like "no filter applied"
+ * rather than like a bug.
+ *
+ * Two facets, because the record has two closed vocabularies. Everything else
+ * on `FeedbackSchema` (`message`, `email`, `pageUrl`) is free text, which the
+ * route already matches through `?search=` across all of them at once; a facet
+ * for one of them would be a worse version of the search that exists.
+ *
+ * `search`, `page`, `limit`, `sortBy`, `sortDirection` and `fields` are reserved
+ * query params, not facets, and are absent for that reason instead.
+ */
+import { object } from "yup";
+import { enumFacet, rejectUnknownKeys } from "../common/facet.schema.js";
+import {
+  SupportedFeedbackStatuses,
+  SupportedFeedbackTypes,
+} from "./feedback.constant.js";
+
+const FeedbackFilterShape = object({
+  type: enumFacet(SupportedFeedbackTypes, "Type"),
+  status: enumFacet(SupportedFeedbackStatuses, "Status"),
+}).label("Feedback Filter");
+
+/**
+ * Wrapped so an unknown key is REJECTED rather than silently ignored, which is
+ * the whole point here: the hand-rolled reader this replaces ignored not just
+ * unknown KEYS but unknown VALUES too.
+ */
+export const FeedbackFilterSchema = rejectUnknownKeys(FeedbackFilterShape, () =>
+  Object.keys(FeedbackFilterShape.fields),
+);

package/src/geo/city-filter.schema.ts

@@ -0,0 +1,41 @@
+/**
+ * The city filter: the closed vocabulary of facets the city endpoints read.
+ *
+ * Shared by both shapes of the same query, exactly as `StateFilterSchema` is:
+ *
+ *   • `GET /geo/countries/:countryCode/states/:stateCode/cities` — the cascade,
+ *     where both codes are PATH params folded into this filter.
+ *   • `GET /geo/cities?search=mum&countryCode=IN` — the flat search, for a user
+ *     typing a city before picking a state.
+ *
+ * The flat route requires at least one of `countryCodes` or `search`: an
+ * unnarrowed call would be a paged walk of ~153,000 rows, which is never what
+ * the caller meant.
+ *
+ * `search`, `page`, `limit`, `sortBy`, `sortDirection` and `fields` are reserved
+ * query params, not facets, and are absent for that reason instead.
+ */
+import { object } from "yup";
+import { codeTokens, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+
+const CityFilterShape = object({
+  /** ISO 3166-1 alpha-2 of the parent country, e.g. `IN`. */
+  countryCodes: codeTokens("Country Codes"),
+
+  /**
+   * BARE subdivision codes, e.g. `KA`. Ambiguous without `countryCodes`; see
+   * `StateFilterSchema.stateCodes` and `@todo STATE-CODE-ISO-PREFIX`.
+   */
+  stateCodes: codeTokens("State Codes"),
+
+  /** Display names, matched exactly. Free-text matching is `?search=`. */
+  names: tokens("Names"),
+}).label("City Filter");
+
+/**
+ * Wrapped so an unknown key is REJECTED rather than silently ignored. See
+ * `SkillFilterSchema` for why this is a `.test()` and not `.noUnknown()`.
+ */
+export const CityFilterSchema = rejectUnknownKeys(CityFilterShape, () =>
+  Object.keys(CityFilterShape.fields),
+);

package/src/geo/city.schema.ts

@@ -0,0 +1,104 @@
+import { array, number, object, string } from "yup";
+import type { InferType } from "yup";
+
+/**
+ * A city in the geo reference mirror, backing
+ * `GET /geo/countries/:countryCode/states/:stateCode/cities` and `GET /geo/cities`.
+ *
+ * The big one: ~153,000 rows, ingested by STREAMING the 182 MB upstream JSON
+ * rather than parsing it. See `CountrySchema` for why this is neither `.strict()`
+ * nor concatenated with `DbDefaultSchema`.
+ *
+ * Both parent levels are stored denormalized (`stateCode`/`stateName` and
+ * `countryCode`/`countryName`), as upstream ships them, so a flat search hit
+ * carries everything a UI needs to back-fill the whole cascade.
+ */
+export const CitySchema = object({
+  /** The upstream dr5hn id. Stable, and the key every upsert matches on. */
+  id: number().integer().required().label("ID"),
+
+  name: string().trim().required().label("Name"),
+
+  stateId: number().integer().optional().nullable().label("State ID"),
+
+  /** The BARE subdivision code. Only meaningful paired with `countryCode`; see `StateSchema`. */
+  stateCode: string().trim().uppercase().optional().nullable().label("State Code"),
+
+  /**
+   * Fully-qualified ISO 3166-2, e.g. `IN-KA`.
+   *
+   * DERIVED on ingest as `${countryCode}-${stateCode}`, because the upstream city
+   * record carries only the bare `state_code` — unlike the state record, which
+   * ships `iso3166_2` directly. Stored anyway so the `@todo STATE-CODE-ISO-PREFIX`
+   * migration can re-point the cities route without a 153k-row re-ingest.
+   * Null when either half is missing.
+   */
+  stateCodeIso: string().trim().uppercase().optional().nullable().label("ISO 3166-2 Code"),
+
+  stateName: string().trim().optional().nullable().label("State Name"),
+
+  countryId: number().integer().optional().nullable().label("Country ID"),
+
+  /** ISO 3166-1 alpha-2 of the parent, UPPERCASE. See `CountrySchema.countryCode`. */
+  countryCode: string().trim().uppercase().length(2).required().label("Country Code"),
+
+  countryName: string().trim().optional().nullable().label("Country Name"),
+
+  /** Numbers, not the strings upstream ships. See `CountrySchema.latitude`. */
+  latitude: number().optional().nullable().label("Latitude"),
+  longitude: number().optional().nullable().label("Longitude"),
+
+  /** The name in its own script. Stored, but NOT searchable; see `searchByLocale`. */
+  native: string().trim().optional().nullable().label("Native Name"),
+
+  type: string().trim().optional().nullable().label("Type"),
+  level: number().integer().optional().nullable().label("Level"),
+  parentId: number().integer().optional().nullable().label("Parent ID"),
+
+  /**
+   * Null on most rows. Worth keeping (it is a good relevance signal when
+   * present) but never worth SORTING by alone, since a null-heavy sort buries
+   * every city upstream has no figure for.
+   */
+  population: number().optional().nullable().label("Population"),
+
+  timezone: string().trim().optional().nullable().label("Timezone"),
+
+  /** Localized names keyed by locale. Unshaped; see `CountrySchema.translations`. */
+  translations: object().optional().nullable().label("Translations"),
+
+  /**
+   * The name field searched for the DEFAULT (English) locale: the canonical
+   * `name`, and nothing else.
+   *
+   * Search is scoped to ONE locale, so the searchable names are split across
+   * this field and `searchByLocale` rather than pooled into one array. A pooled
+   * field would make every locale's search implicitly a search of all 19
+   * languages: a French UI searching "Inde" would also match German "Indien".
+   */
+  searchDefault: array().of(string().required()).optional().default([]).label("Search Default"),
+
+  /**
+   * Per-locale name fields, keyed by lowercased BCP-47 tag (`de`, `pt-br`).
+   * Each carries ONLY that locale's translation, which is what makes
+   * `?locale=de` German and not "German plus everything that looks similar".
+   *
+   * Unshaped for the same reason as `translations`: the key set is upstream's.
+   *
+   * `native` is deliberately NOT indexed here. It cannot be attributed to a
+   * language with this data — 84% of city native names equal SEVERAL locales'
+   * translations (Latin spellings coinciding across de/it/nl/hr/pl) while
+   * distinctive non-Latin names like `भारत` match none — so filing `कर्नाटक`
+   * under German would be worse than not indexing it at all.
+   *
+   * The 19 upstream locales are br, ko, pt-BR, pt, nl, hr, fa, de, es, fr, ja,
+   * it, zh-CN, tr, ru, uk, pl, hi, ar. **`sv` is absent**, so a Swedish search
+   * matches nothing. That is the accepted cost of strict scoping.
+   */
+  searchByLocale: object().optional().nullable().label("Search By Locale"),
+
+  /** Epoch ms of the run that last wrote this row. Drives the stale-row prune. */
+  syncedAt: number().optional().nullable().label("Synced At"),
+}).label("City");
+
+export type City = InferType<typeof CitySchema>;

package/src/geo/country-filter.schema.ts

@@ -0,0 +1,47 @@
+/**
+ * The country filter: the closed vocabulary of facets `GET /geo/countries` reads.
+ *
+ * The counterpart of `SkillFilterSchema` and `FeedbackFilterSchema`, and it
+ * exists for the same reason: a filter parser that accepts any key passes a
+ * misspelled facet straight to Mongo, which is not a narrower query but a query
+ * for a field no document has — 200 OK, zero rows, no error anywhere.
+ *
+ * Every facet is a field `CountrySchema` actually declares and that someone
+ * would plausibly group by. ABSENT on purpose: `currency`, `tld`, `phonecode`
+ * and the rest, which are display values, not things you filter a dropdown by;
+ * and `native`/`translations`, which are reachable through `?search=` instead —
+ * a facet on them would be exact-match on a value the user cannot be expected to
+ * type exactly.
+ *
+ * `search`, `page`, `limit`, `sortBy`, `sortDirection` and `fields` are reserved
+ * query params, not facets, and are absent for that reason instead.
+ */
+import { object } from "yup";
+import { codeTokens, rejectUnknownKeys, tokens } from "../common/facet.schema.js";
+
+const CountryFilterShape = object({
+  /** ISO 3166-1 alpha-2 codes, e.g. `IN`. Uppercased, matching how they are stored. */
+  countryCodes: codeTokens("Country Codes"),
+
+  /** ISO 3166-1 alpha-3 codes, e.g. `IND`. */
+  iso3s: codeTokens("ISO3 Codes"),
+
+  /**
+   * `tokens`, NOT `codeTokens`: a region is a display string ("Asia", "Europe"),
+   * and uppercasing it would match nothing.
+   */
+  regions: tokens("Regions"),
+
+  subregions: tokens("Subregions"),
+
+  /** Display names, matched exactly. Free-text matching is `?search=`. */
+  names: tokens("Names"),
+}).label("Country Filter");
+
+/**
+ * Wrapped so an unknown key is REJECTED rather than silently ignored. See
+ * `SkillFilterSchema` for why this is a `.test()` and not `.noUnknown()`.
+ */
+export const CountryFilterSchema = rejectUnknownKeys(CountryFilterShape, () =>
+  Object.keys(CountryFilterShape.fields),
+);