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

package/src/api/pin.ts

@@ -1,27 +1,23 @@
 import * as z from 'zod/mini';
 
-import { renderRepoCard } from '../cards/repo.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchRepo } from '../fetchers/repo.js';
+import { renderRepoCard } from '../cards/repo.ts';
+import { fetchRepo } from '../fetchers/repo.ts';
 
-import type { ApiResult } from './api-result.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   listParam,
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
   rawParam,
   safeParam,
-} from './params.js';
+  usernameParam,
+} from './params.ts';
 
 /** What the pin endpoint accepts, on top of the shared color params. */
 const pinQuery = z.object({
-  username: safeParam,
+  username: usernameParam,
   repo: safeParam,
   hide_border: booleanParam,
   card_width: looseIntParam,
@@ -37,41 +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.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username the repository belongs to.
- * @param query.repo Repository name.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.show_owner Whether to show the repository owner.
- * @param query.browser_rendering Whether the browser wraps the description text.
- * @param query.show Comma-separated extra stats to show.
- * @param query.show_icons Whether to show the stat icons.
- * @param query.number_format How numbers are abbreviated.
- * @param query.text_bold Whether the stat values are bold.
- * @param query.line_height Line height between the stats.
- * @param query.locale Language the card is rendered in.
- * @param query.border_radius Card border radius.
- * @param query.description_lines_count Lines the description is wrapped to.
- * @param config Deployment config supplying the PAT pool.
  * @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 (err) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
-  }
-
-  try {
-    const {
+const renderPin = cardHandler(
+  pinQuery,
+  async (
+    {
       username,
       repo,
       hide_border,
@@ -86,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,
@@ -101,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 (err) {
-    return errorResult(err, 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,100 +1,65 @@
 import * as z from 'zod/mini';
 
-import { RANK_ICONS, renderStatsCard } from '../cards/stats.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchStats } from '../fetchers/stats.js';
+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.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   enumParam,
+  fromParam,
   listParam,
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
+  ORDERED_RANGE,
   rawParam,
   safeListParam,
-  safeParam,
-  yearParam,
-} from './params.js';
+  toParam,
+  usernameParam,
+} from './params.ts';
 
 /** What the stats endpoint accepts, on top of the shared color params. */
-const statsQuery = z.object({
-  username: safeParam,
-  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.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username.
- * @param query.repo Comma-separated repositories the search-based stats are scoped to.
- * @param query.owner Comma-separated owners the search-based stats are scoped to.
- * @param query.hide Comma-separated stats to hide.
- * @param query.hide_title Whether to hide the card title.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.hide_rank Whether to hide the rank circle.
- * @param query.show_icons Whether to show the stat icons.
- * @param query.include_all_commits Whether to count commits of all time.
- * @param query.commits_year Year the commits are counted for.
- * @param query.line_height Line height between the stats.
- * @param query.text_bold Whether the stat values are bold.
- * @param query.exclude_repo Comma-separated repositories to exclude.
- * @param query.custom_title Card title.
- * @param query.locale Language the card is rendered in.
- * @param query.disable_animations Whether to disable the card animations.
- * @param query.border_radius Card border radius.
- * @param query.number_format How numbers are abbreviated.
- * @param query.role Comma-separated owner affiliations to include.
- * @param query.number_precision Decimals kept when a number is abbreviated.
- * @param query.rank_icon Which rank indicator to draw.
- * @param query.show Comma-separated extra stats to show.
- * @param query.contribs_include_own_repos Whether the contributed-to counts include the user's own repositories.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
-const renderStats = async (query: StatsApiQuery, config: CardConfig): Promise<ApiResult> => {
-  let colors;
-  try {
-    colors = parseColorParams(query);
-  } catch (err) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
-  }
-
-  try {
-    const {
+const renderStats = cardHandler(
+  statsQuery,
+  async (
+    {
       username,
       repo,
       owner,
@@ -105,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,
@@ -119,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}`,
@@ -135,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'),
@@ -151,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 (err) {
-    return errorResult(err, 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.js';
-import type { CardConfig } from '../common/config.js';
-import { fetchTopLanguages } from '../fetchers/top-languages.js';
+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.js';
-import { errorResult } from './api-result.js';
-import type { ApiQuery } from './params.js';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   enumParam,
@@ -18,20 +12,18 @@ import {
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
   rawParam,
-  safeParam,
-} from './params.js';
+  usernameParam,
+} from './params.ts';
 
 /** What the top-languages endpoint accepts, on top of the shared color params. */
 const topLangsQuery = z.object({
-  username: safeParam,
+  username: usernameParam,
   hide: listParam,
   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,48 +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.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username.
- * @param query.hide Comma-separated languages to hide.
- * @param query.hide_title Whether to hide the card title.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.layout How the languages are laid out.
- * @param query.langs_count Number of languages to show.
- * @param query.exclude_repo Comma-separated repositories to exclude.
- * @param query.size_weight Weight given to a language's size.
- * @param query.count_weight Weight given to a language's repository count.
- * @param query.custom_title Card title.
- * @param query.locale Language the card is rendered in.
- * @param query.border_radius Card border radius.
- * @param query.role Comma-separated owner affiliations to include.
- * @param query.disable_animations Whether to disable the card animations.
- * @param query.hide_progress Whether to hide the progress bars.
- * @param query.hide_values Whether to hide the language values.
- * @param query.stats_format Whether values are shown as bytes or percentages.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
-const renderTopLangs = async (query: TopLangsApiQuery, config: CardConfig): Promise<ApiResult> => {
-  let colors;
-  try {
-    colors = parseColorParams(query);
-  } catch (err) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(err);
-  }
-
-  try {
-    const {
+const renderTopLangs = cardHandler(
+  topLangsQuery,
+  async (
+    {
       username,
       hide,
       hide_title,
@@ -103,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,
@@ -116,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 (err) {
-    return errorResult(err, 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 },
 });