@stats-forge/github-stats-forge-core 0.1.0 → 0.2.0

package/src/api/params.ts

@@ -3,6 +3,7 @@ import * as z from 'zod/mini';
 import type { ColorParams } from '../common/color.ts';
 import { COLOR_PARAM_KEYS, THEME_PARAM_KEYS, isValidColorInput } from '../common/color.ts';
 import { GITHUB_USERNAME_PATTERN } from '../common/constants.ts';
+import { getWidestRange, parseRangeDate } from '../common/date.ts';
 import { CardError } from '../common/error.ts';
 import { parseArray, parseBoolean } from '../common/ops.ts';
 import { isLocaleAvailable } from '../translations.ts';
@@ -24,7 +25,16 @@ const rawParam = z.optional(z.string());
 const SAFE_PATTERN = /^[-\w/.,]+$/;
 
 /** What a check rejected a param for. */
-type Rejection = 'number' | 'year' | 'unsafe' | 'username' | 'locale' | 'enum' | 'color';
+type Rejection =
+  | 'number'
+  | 'date'
+  | 'out_of_range'
+  | 'inverted_range'
+  | 'unsafe'
+  | 'username'
+  | 'locale'
+  | 'enum'
+  | 'color';
 
 /**
  * Every rejection the api can put on an error card, in one place.
@@ -32,7 +42,9 @@ type Rejection = 'number' | 'year' | 'unsafe' | 'username' | 'locale' | 'enum' |
  */
 const REJECTION_MESSAGES: Record<Rejection, (param: string) => string> = {
   number: (param) => `Invalid number input for parameter "${param}"`,
-  year: (param) => `Invalid number input for parameter "${param}"`,
+  date: (param) => `Invalid date input for parameter "${param}"`,
+  out_of_range: (param) => `Out of range date for parameter "${param}"`,
+  inverted_range: () => 'Range "from" is after "to"',
   unsafe: (param) => `Parameter "${param}" contains unsafe characters`,
   username: (param) => `Invalid username input for parameter "${param}"`,
   locale: () => 'Locale not found',
@@ -86,13 +98,38 @@ const looseIntParam = z.pipe(
 );
 
 /**
- * A four-digit year.
- * Anything else builds a `DateTime` GitHub rejects, so it is a permanent error here rather than a failed request later.
- * Yields the year, or `undefined` when the param is absent.
+ * One end of the range a card counts within, written as `2024`, `2024-03` or `2024-03-15`.
+ *
+ * @returns Schema yielding the instant, or `undefined` when the param is absent.
+ */
+const rangeParam = (end: 'from' | 'to'): z.ZodMiniType<Date | undefined, string | undefined> => {
+  const parse = (value: string): Date | undefined => parseRangeDate(value, end);
+  return z.pipe(
+    rawParam.check(rejects('date', (value) => parse(value) !== undefined)).check(
+      rejects('out_of_range', (value) => {
+        const date = parse(value);
+        const widest = getWidestRange();
+        // a bad shape is already reported by the check above
+        return date === undefined || (date >= widest.from && date <= widest.to);
+      }),
+    ),
+    z.transform((value) => (value === undefined ? undefined : parse(value))),
+  );
+};
+
+/** The start of a card's range; see {@link rangeParam}. */
+const fromParam = rangeParam('from');
+
+/** The end of a card's range; see {@link rangeParam}. */
+const toParam = rangeParam('to');
+
+/**
+ * The pair-level rule the two ends cannot see on their own.
+ * Every endpoint taking a range applies it, so an order no card could draw is rejected once.
  */
-const yearParam: z.ZodMiniType<number | undefined, string | undefined> = z.pipe(
-  rawParam.check(rejects('year', (value) => /^\d{4}$/.test(value))),
-  z.transform((value) => (value === undefined ? undefined : Number(value))),
+const ORDERED_RANGE = z.refine<{ from?: Date | undefined; to?: Date | undefined }>(
+  ({ from, to }) => from === undefined || to === undefined || from <= to,
+  { error: REJECTION_MESSAGES.inverted_range('from'), path: ['from'] },
 );
 
 /**
@@ -213,7 +250,9 @@ export type { ApiQuery };
 export {
   booleanParam,
   enumParam,
+  fromParam,
   listParam,
+  ORDERED_RANGE,
   localeParam,
   looseIntParam,
   numberParam,
@@ -222,6 +261,6 @@ export {
   rawParam,
   safeListParam,
   safeParam,
+  toParam,
   usernameParam,
-  yearParam,
 };

package/src/api/pin.ts

@@ -1,20 +1,15 @@
 import * as z from 'zod/mini';
 
 import { renderRepoCard } from '../cards/repo.ts';
-import type { CardConfig } from '../common/config.ts';
 import { fetchRepo } from '../fetchers/repo.ts';
 
-import type { ApiResult } from './api-result.ts';
-import { errorResult } from './api-result.ts';
-import type { ApiQuery } from './params.ts';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   listParam,
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
   rawParam,
   safeParam,
   usernameParam,
@@ -38,25 +33,15 @@ const pinQuery = z.object({
   description_lines_count: looseIntParam,
 });
 
-/** The query this endpoint accepts, checked against the schema above. */
-type PinApiQuery = ApiQuery<typeof pinQuery>;
-
 /**
  * Render the repository card for a set of query params.
  *
  * @returns The rendered card, or a rendered error.
  */
-export const pin = async (query: PinApiQuery, config: CardConfig): Promise<ApiResult> => {
-  let colors;
-  try {
-    colors = parseColorParams(query);
-  } catch (error) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(error);
-  }
-
-  try {
-    const {
+const renderPin = cardHandler(
+  pinQuery,
+  async (
+    {
       username,
       repo,
       hide_border,
@@ -71,8 +56,10 @@ export const pin = async (query: PinApiQuery, config: CardConfig): Promise<ApiRe
       locale,
       border_radius,
       description_lines_count,
-    } = parseParams(pinQuery, query);
-
+    },
+    colors,
+    config,
+  ) => {
     const repoData = await fetchRepo(
       {
         username,
@@ -86,26 +73,27 @@ export const pin = async (query: PinApiQuery, config: CardConfig): Promise<ApiRe
       config,
     );
 
-    return {
-      status: 'success',
-      content: renderRepoCard(repoData, {
-        ...colors,
-        hide_border,
-        border_radius,
-        card_width_input: card_width,
-        show_owner,
-        browser_rendering,
-        show,
-        show_icons,
-        number_format,
-        text_bold,
-        line_height,
-        username,
-        locale,
-        description_lines_count,
-      }),
-    };
-  } catch (error) {
-    return errorResult(error, colors);
-  }
-};
+    return renderRepoCard(repoData, {
+      ...colors,
+      hide_border,
+      border_radius,
+      card_width_input: card_width,
+      show_owner,
+      browser_rendering,
+      show,
+      show_icons,
+      number_format,
+      text_bold,
+      line_height,
+      username,
+      locale,
+      description_lines_count,
+    });
+  },
+);
+
+/**
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * A UI reads them off the function it calls: `pin.OPTIONS.show`.
+ */
+export const pin = Object.assign(renderPin, { OPTIONS: renderRepoCard.OPTIONS });

package/src/api/stats.ts

@@ -1,74 +1,65 @@
 import * as z from 'zod/mini';
 
-import { RANK_ICONS, renderStatsCard } from '../cards/stats.ts';
-import type { CardConfig } from '../common/config.ts';
+import { renderStatsCard } from '../cards/stats.ts';
+import { OWNER_AFFILIATIONS } from '../common/constants.ts';
 import { fetchStats } from '../fetchers/stats.ts';
 
-import type { ApiResult } from './api-result.ts';
-import { errorResult } from './api-result.ts';
-import type { ApiQuery } from './params.ts';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   enumParam,
+  fromParam,
   listParam,
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
+  ORDERED_RANGE,
   rawParam,
   safeListParam,
+  toParam,
   usernameParam,
-  yearParam,
 } from './params.ts';
 
 /** What the stats endpoint accepts, on top of the shared color params. */
-const statsQuery = z.object({
-  username: usernameParam,
-  repo: safeListParam,
-  owner: safeListParam,
-  hide: listParam,
-  hide_title: booleanParam,
-  hide_border: booleanParam,
-  card_width: looseIntParam,
-  hide_rank: booleanParam,
-  show_icons: booleanParam,
-  include_all_commits: booleanParam,
-  commits_year: yearParam,
-  line_height: rawParam,
-  text_bold: booleanParam,
-  exclude_repo: listParam,
-  custom_title: rawParam,
-  locale: localeParam,
-  disable_animations: booleanParam,
-  border_radius: numberParam,
-  number_format: rawParam,
-  role: listParam,
-  number_precision: looseIntParam,
-  rank_icon: enumParam(RANK_ICONS),
-  show: listParam,
-  contribs_include_own_repos: booleanParam,
-});
-
-/** The query this endpoint accepts, checked against the schema above. */
-type StatsApiQuery = ApiQuery<typeof statsQuery>;
+const statsQuery = z
+  .object({
+    username: usernameParam,
+    repo: safeListParam,
+    owner: safeListParam,
+    hide: listParam,
+    hide_title: booleanParam,
+    hide_border: booleanParam,
+    card_width: looseIntParam,
+    hide_rank: booleanParam,
+    show_icons: booleanParam,
+    include_all_commits: booleanParam,
+    from: fromParam,
+    to: toParam,
+    line_height: rawParam,
+    text_bold: booleanParam,
+    exclude_repo: listParam,
+    custom_title: rawParam,
+    locale: localeParam,
+    disable_animations: booleanParam,
+    border_radius: numberParam,
+    number_format: rawParam,
+    role: listParam,
+    number_precision: looseIntParam,
+    rank_icon: enumParam(renderStatsCard.OPTIONS.rank_icon),
+    show: listParam,
+    contribs_include_own_repos: booleanParam,
+  })
+  .check(ORDERED_RANGE);
 
 /**
  * Render the stats card for a set of query params.
  *
  * @returns The rendered card, or a rendered error.
  */
-const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<ApiResult> => {
-  let colors;
-  try {
-    colors = parseColorParams(query);
-  } catch (error) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(error);
-  }
-
-  try {
-    const {
+const renderStats = cardHandler(
+  statsQuery,
+  async (
+    {
       username,
       repo,
       owner,
@@ -79,7 +70,8 @@ const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<Ap
       hide_rank,
       show_icons,
       include_all_commits,
-      commits_year,
+      from,
+      to,
       line_height,
       text_bold,
       exclude_repo,
@@ -93,8 +85,10 @@ const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<Ap
       rank_icon,
       show,
       contribs_include_own_repos,
-    } = parseParams(statsQuery, query);
-
+    },
+    colors,
+    config,
+  ) => {
     // A bare repo name is scoped to the user whose card this is.
     const repository = repo.map((name) =>
       name.includes('/') ? name : `${username ?? ''}/${name}`,
@@ -109,7 +103,8 @@ const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<Ap
           show.includes('prs_merged') || show.includes('prs_merged_percentage'),
         include_discussions: show.includes('discussions_started'),
         include_discussions_answers: show.includes('discussions_answered'),
-        commits_year,
+        from,
+        to,
         repo: repository,
         owner,
         include_prs_authored: show.includes('prs_authored'),
@@ -125,45 +120,39 @@ const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<Ap
       config,
     );
 
-    return {
-      status: 'success',
-      content: renderStatsCard(
-        stats,
-        {
-          ...colors,
-          hide,
-          show_icons,
-          hide_title,
-          hide_border,
-          card_width,
-          hide_rank,
-          include_all_commits,
-          commits_year,
-          line_height,
-          text_bold,
-          custom_title,
-          border_radius,
-          number_format,
-          number_precision,
-          locale,
-          disable_animations,
-          rank_icon,
-          show,
-        },
-        username,
-        repository,
-        owner,
-      ),
-    };
-  } catch (error) {
-    return errorResult(error, colors);
-  }
-};
+    return renderStatsCard(
+      stats,
+      {
+        ...colors,
+        hide,
+        show_icons,
+        hide_title,
+        hide_border,
+        card_width,
+        hide_rank,
+        include_all_commits,
+        line_height,
+        text_bold,
+        custom_title,
+        border_radius,
+        number_format,
+        number_precision,
+        locale,
+        disable_animations,
+        rank_icon,
+        show,
+      },
+      username,
+      repository,
+      owner,
+    );
+  },
+);
 
 /**
- * The card, with the values its enum params accept.
- * A UI reads them off the function it calls, e.g. `stats.LAYOUTS`.
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * A UI reads them off the function it calls: `stats.OPTIONS.rank_icon`.
  */
 export const stats = Object.assign(renderStats, {
-  RANK_ICONS,
+  OPTIONS: { ...renderStatsCard.OPTIONS, role: OWNER_AFFILIATIONS },
 });

package/src/api/top-langs.ts

@@ -1,16 +1,10 @@
 import * as z from 'zod/mini';
 
-import {
-  TOP_LANG_LAYOUTS,
-  TOP_LANG_STATS_FORMATS,
-  renderTopLanguages,
-} from '../cards/top-languages.ts';
-import type { CardConfig } from '../common/config.ts';
+import { renderTopLanguages } from '../cards/top-languages.ts';
+import { OWNER_AFFILIATIONS } from '../common/constants.ts';
 import { fetchTopLanguages } from '../fetchers/top-languages.ts';
 
-import type { ApiResult } from './api-result.ts';
-import { errorResult } from './api-result.ts';
-import type { ApiQuery } from './params.ts';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   enumParam,
@@ -18,8 +12,6 @@ import {
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
   rawParam,
   usernameParam,
 } from './params.ts';
@@ -31,7 +23,7 @@ const topLangsQuery = z.object({
   hide_title: booleanParam,
   hide_border: booleanParam,
   card_width: looseIntParam,
-  layout: enumParam(TOP_LANG_LAYOUTS),
+  layout: enumParam(renderTopLanguages.OPTIONS.layout),
   langs_count: looseIntParam,
   exclude_repo: listParam,
   size_weight: numberParam,
@@ -43,28 +35,18 @@ const topLangsQuery = z.object({
   disable_animations: booleanParam,
   hide_progress: booleanParam,
   hide_values: booleanParam,
-  stats_format: enumParam(TOP_LANG_STATS_FORMATS),
+  stats_format: enumParam(renderTopLanguages.OPTIONS.stats_format),
 });
 
-/** The query this endpoint accepts, checked against the schema above. */
-type TopLangsApiQuery = ApiQuery<typeof topLangsQuery>;
-
 /**
  * Render the top languages card for a set of query params.
  *
  * @returns The rendered card, or a rendered error.
  */
-const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Promise<ApiResult> => {
-  let colors;
-  try {
-    colors = parseColorParams(query);
-  } catch (error) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(error);
-  }
-
-  try {
-    const {
+const renderTopLangs = cardHandler(
+  topLangsQuery,
+  async (
+    {
       username,
       hide,
       hide_title,
@@ -83,8 +65,10 @@ const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Prom
       hide_progress,
       hide_values,
       stats_format,
-    } = parseParams(topLangsQuery, query);
-
+    },
+    colors,
+    config,
+  ) => {
     const topLangs = await fetchTopLanguages(
       {
         username,
@@ -96,35 +80,29 @@ const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Prom
       config,
     );
 
-    return {
-      status: 'success',
-      content: renderTopLanguages(topLangs, {
-        ...colors,
-        custom_title,
-        hide_title,
-        hide_border,
-        card_width,
-        hide,
-        layout,
-        langs_count,
-        border_radius,
-        locale,
-        disable_animations,
-        hide_progress,
-        hide_values,
-        stats_format,
-      }),
-    };
-  } catch (error) {
-    return errorResult(error, colors);
-  }
-};
+    return renderTopLanguages(topLangs, {
+      ...colors,
+      custom_title,
+      hide_title,
+      hide_border,
+      card_width,
+      hide,
+      layout,
+      langs_count,
+      border_radius,
+      locale,
+      disable_animations,
+      hide_progress,
+      hide_values,
+      stats_format,
+    });
+  },
+);
 
 /**
- * The card, with the values its enum params accept.
- * A UI reads them off the function it calls, e.g. `topLangs.LAYOUTS`.
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * A UI reads them off the function it calls: `topLangs.OPTIONS.layout`.
  */
 export const topLangs = Object.assign(renderTopLangs, {
-  LAYOUTS: TOP_LANG_LAYOUTS,
-  STATS_FORMATS: TOP_LANG_STATS_FORMATS,
+  OPTIONS: { ...renderTopLanguages.OPTIONS, role: OWNER_AFFILIATIONS },
 });