@adonisjs/content 1.3.0 → 1.4.0

package/README.md

@@ -15,7 +15,8 @@ We use this package for all official AdonisJS websites to manage docs, blog post
 **Key Features:**
 
 - **Type-safe collections** with VineJS schema validation
-- **GitHub loaders** for sponsors, releases, and contributors
+- **GitHub loaders** for sponsors, releases, contributors, and aggregated OSS statistics
+- **npm package statistics** aggregation with download counts
 - **Custom query methods** for filtering and transforming data
 - **JSON file loading** with validation
 - **Vite integration** for asset path resolution
@@ -178,6 +179,52 @@ const contributors = new Collection({
 })
 ```
 
+### OSS Stats Loader
+
+Aggregate open source statistics from multiple sources including GitHub stars and npm package downloads:
+
+```ts
+import vine from '@vinejs/vine'
+import app from '@adonisjs/core/services/app'
+import { Collection } from '@adonisjs/content'
+import { loaders } from '@adonisjs/content/loaders'
+
+const statsSchema = vine.object({
+  stars: vine.number(),
+  installs: vine.number(),
+})
+
+const ossStatsLoader = loaders.ossStats({
+  outputPath: app.makePath('cache/oss-stats.json'),
+  refresh: 'daily',
+  sources: [
+    {
+      type: 'github',
+      org: 'adonisjs',
+      ghToken: process.env.GITHUB_TOKEN!,
+    },
+    {
+      type: 'npm',
+      packages: [
+        { name: '@adonisjs/core', startDate: '2020-01-01' },
+        { name: '@adonisjs/lucid', startDate: '2020-01-01' },
+      ],
+    },
+  ],
+})
+
+const ossStats = new Collection({
+  schema: statsSchema,
+  loader: ossStatsLoader,
+  cache: true,
+})
+
+const query = await ossStats.load()
+const stats = query.all()
+console.log(`Total GitHub stars: ${stats.stars}`)
+console.log(`Total npm downloads: ${stats.installs}`)
+```
+
 ### Custom Views
 
 Views allow you to define reusable query methods with full type safety:

package/build/chunk-WO5VTK7D.js

@@ -0,0 +1,331 @@
+import {
+  debug_default
+} from "./chunk-LB6JFRVG.js";
+
+// src/utils.ts
+import { Octokit } from "@octokit/rest";
+import { graphql } from "@octokit/graphql";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import dayjs from "dayjs";
+import { dirname } from "path";
+async function fetchAllSponsors({
+  login,
+  isOrg,
+  ghToken
+}) {
+  let hasNext = true;
+  let cursor = null;
+  const allSponsors = [];
+  const query = `
+    query($login: String!, $cursor: String) {
+      ${isOrg ? `organization(login: $login)` : `user(login: $login)`} {
+        sponsorshipsAsMaintainer(first: 100, after: $cursor) {
+          nodes {
+            id
+            createdAt
+            privacyLevel
+            isActive
+            tier {
+              name
+              isOneTime
+              monthlyPriceInCents
+            }
+            sponsorEntity {
+              __typename
+              ... on User {
+                login
+                name
+                avatarUrl
+                url
+              }
+              ... on Organization {
+                login
+                name
+                avatarUrl
+                url
+              }
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    }
+  `;
+  while (hasNext) {
+    const data = await graphql(query, {
+      headers: {
+        authorization: `token ${ghToken}`
+      },
+      login,
+      cursor
+    });
+    const root = isOrg ? data.organization : data.user;
+    if (!root) {
+      break;
+    }
+    const conn = root.sponsorshipsAsMaintainer;
+    if (!conn || !conn.nodes) {
+      break;
+    }
+    for (const node of conn.nodes) {
+      const sponsorEntity = node.sponsorEntity;
+      allSponsors.push({
+        id: node.id,
+        createdAt: node.createdAt,
+        privacyLevel: node.privacyLevel,
+        tierName: node.tier?.name ?? null,
+        tierMonthlyPriceInCents: node.tier?.monthlyPriceInCents ?? null,
+        sponsorType: sponsorEntity.__typename,
+        sponsorLogin: sponsorEntity.login,
+        sponsorName: sponsorEntity.name ?? null,
+        sponsorAvatarUrl: sponsorEntity.avatarUrl ?? null,
+        sponsorUrl: sponsorEntity.url ?? null
+      });
+    }
+    hasNext = conn.pageInfo.hasNextPage;
+    cursor = conn.pageInfo.endCursor;
+  }
+  return allSponsors;
+}
+async function fetchReleases({
+  org,
+  ghToken,
+  filters
+}) {
+  let hasMoreRepos = true;
+  let orgCursor = null;
+  const allReleases = [];
+  while (hasMoreRepos) {
+    const query = `
+      query($cursor: String) {
+        organization(login: "${org}") {
+          repositories(
+            first: 10
+            after: $cursor
+            privacy: PUBLIC
+            isArchived: false
+          ) {
+            nodes {
+              name
+              releases(first: 50, orderBy: {field: CREATED_AT, direction: DESC}) {
+                nodes {
+                  name
+                  tagName
+                  publishedAt
+                  url
+                  description
+                }
+                pageInfo {
+                  endCursor
+                  hasNextPage
+                }
+              }
+            }
+            pageInfo {
+              endCursor
+              hasNextPage
+            }
+          }
+        }
+      }
+    `;
+    const data = await graphql(query, {
+      headers: {
+        authorization: `token ${ghToken}`
+      },
+      cursor: orgCursor
+    });
+    for (const repo of data.organization.repositories.nodes) {
+      const filtered = repo.releases.nodes.filter((r) => {
+        if (!filters) {
+          return true;
+        }
+        let pickRelease = true;
+        if (filters.nameDoesntInclude) {
+          pickRelease = !filters.nameDoesntInclude.some((substr) => r.name.includes(substr));
+        }
+        if (pickRelease && filters.nameIncludes) {
+          pickRelease = filters.nameIncludes.some((substr) => r.name.includes(substr));
+        }
+        return pickRelease;
+      }).map((r) => ({
+        repo: repo.name,
+        ...r
+      }));
+      allReleases.push(...filtered);
+    }
+    hasMoreRepos = data.organization.repositories.pageInfo.hasNextPage;
+    orgCursor = data.organization.repositories.pageInfo.endCursor;
+  }
+  return allReleases;
+}
+async function fetchContributorsForOrg({
+  org,
+  ghToken
+}) {
+  const REPO_PAGE_SIZE = 100;
+  const CONTRIB_PAGE_SIZE = 100;
+  const octokit = new Octokit({ auth: ghToken });
+  const repos = await octokit.paginate(octokit.repos.listForOrg, {
+    org,
+    type: "public",
+    per_page: REPO_PAGE_SIZE
+  });
+  const activeRepos = repos.filter((r) => !r.archived);
+  const result = [];
+  for (const repo of activeRepos) {
+    const repoName = repo.name;
+    try {
+      const contributors = await octokit.paginate(
+        octokit.repos.listContributors,
+        {
+          owner: org,
+          repo: repoName,
+          per_page: CONTRIB_PAGE_SIZE
+        },
+        (response) => response.data
+      );
+      contributors.forEach((c) => {
+        if (c.login) {
+          result.push({
+            login: c.login,
+            id: c.id,
+            avatar_url: c.avatar_url ?? null,
+            html_url: c.html_url ?? null,
+            contributions: c.contributions ?? 0
+          });
+        }
+      });
+    } catch (err) {
+      console.warn(
+        `Warning: failed to fetch contributors for ${org}/${repoName}: ${err?.message ?? err}`
+      );
+    }
+  }
+  return result;
+}
+function mergeArrays(existing, fresh, key) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const r of [...existing, ...fresh]) {
+    if (!seen.has(r[key])) {
+      seen.add(r[key]);
+      deduped.push(r);
+    }
+  }
+  return deduped;
+}
+async function aggregateInstalls(packages) {
+  let total = 0;
+  for (let pkg of packages) {
+    const startDate = pkg.startDate;
+    const endDate = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const res = await fetch(
+      `https://api.npmjs.org/downloads/point/${startDate}:${endDate}/${pkg.name}`
+    );
+    const data = await res.json();
+    total += data.downloads;
+  }
+  return total;
+}
+async function aggregateStars({
+  org,
+  ghToken
+}) {
+  let totalStars = 0;
+  const octokit = new Octokit({ auth: ghToken });
+  await octokit.paginate(
+    octokit.repos.listForOrg,
+    {
+      org,
+      type: "public",
+      per_page: 100
+    },
+    (response) => {
+      for (const repo of response.data) {
+        if (!repo.archived && repo.stargazers_count) {
+          totalStars += repo.stargazers_count;
+        }
+      }
+      return response.data;
+    }
+  );
+  return totalStars;
+}
+function createCache({
+  key,
+  outputPath,
+  refresh
+}) {
+  function isExpired(fetchDate) {
+    switch (refresh) {
+      case "daily":
+        return dayjs().isAfter(fetchDate, "day");
+      case "weekly":
+        return dayjs().isAfter(fetchDate, "week");
+      case "monthly":
+        return dayjs().isAfter(fetchDate, "month");
+    }
+  }
+  return {
+    /**
+     * Retrieves cached data from disk if it exists and hasn't expired.
+     * Returns null if the cache doesn't exist, is expired, or the file is not found.
+     *
+     * @example
+     * ```ts
+     * const data = await cache.get()
+     * if (data === null) {
+     *   console.log('Cache expired or not found')
+     * }
+     * ```
+     */
+    async get() {
+      try {
+        debug_default('loading %s from file "%s"', key, outputPath);
+        const cachedContents = JSON.parse(await readFile(outputPath, "utf-8"));
+        if (!cachedContents || isExpired(new Date(cachedContents.lastFetched))) {
+          return null;
+        }
+        return cachedContents[key];
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      return null;
+    },
+    /**
+     * Saves data to the cache file with the current timestamp.
+     * Creates the directory structure if it doesn't exist.
+     *
+     * @param contents - The data to cache
+     *
+     * @example
+     * ```ts
+     * const freshData = await fetchDataFromAPI()
+     * await cache.put(freshData)
+     * ```
+     */
+    async put(contents) {
+      debug_default('caching %s "%s"', key, outputPath);
+      const fileContents = { lastFetched: (/* @__PURE__ */ new Date()).toISOString(), [key]: contents };
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, JSON.stringify(fileContents));
+      return contents;
+    }
+  };
+}
+
+export {
+  fetchAllSponsors,
+  fetchReleases,
+  fetchContributorsForOrg,
+  mergeArrays,
+  aggregateInstalls,
+  aggregateStars,
+  createCache
+};

package/build/index.d.ts

@@ -1,2 +1,3 @@
 export { Collection } from './src/collection.ts';
 export { configure } from './configure.ts';
+export { createCache } from './src/utils.ts';

package/build/index.js

@@ -1,6 +1,9 @@
 import {
   Collection
 } from "./chunk-Q6QIMTOW.js";
+import {
+  createCache
+} from "./chunk-WO5VTK7D.js";
 import "./chunk-LB6JFRVG.js";
 
 // configure.ts
@@ -12,5 +15,6 @@ async function configure(command) {
 }
 export {
   Collection,
-  configure
+  configure,
+  createCache
 };

package/build/src/debug.d.ts

@@ -7,5 +7,5 @@
  * debug('loading file "%s"', filePath)
  * ```
  */
-declare const _default: import("util").DebugLogger;
+declare const _default: import("node:util").DebugLogger;
 export default _default;

package/build/src/loaders/main.d.ts

@@ -1,8 +1,9 @@
-import { type GithubSponsorsOptions, type GithubReleasesOptions, type GithubContributorsOptions } from '../types.ts';
+import { type GithubSponsorsOptions, type GithubReleasesOptions, type GithubContributorsOptions, type OssStatsOptions } from '../types.ts';
+import { JsonLoader } from './json.ts';
+import { OssStatsLoader } from './oss_stats.ts';
 import { GithubSponsorsLoader } from './gh_sponsors.ts';
 import { GithubReleasesLoader } from './gh_releases.ts';
 import { GithubContributorsLoader } from './gh_contributors.ts';
-import { JsonLoader } from './json.ts';
 /**
  * Factory functions for creating content loaders.
  * Provides convenient access to GitHub-based data loaders.
@@ -77,6 +78,33 @@ export declare const loaders: {
      * ```
      */
     ghReleases(options: GithubReleasesOptions): GithubReleasesLoader<import("@vinejs/vine/types").SchemaTypes>;
+    /**
+     * Creates an OSS statistics loader instance.
+     *
+     * @param options - Configuration options for the OSS stats loader
+     *
+     * @example
+     * ```ts
+     * const loader = loaders.ossStats({
+     *   outputPath: './cache/oss-stats.json',
+     *   refresh: 'daily',
+     *   sources: [
+     *     {
+     *       type: 'github',
+     *       org: 'adonisjs',
+     *       ghToken: process.env.GITHUB_TOKEN
+     *     },
+     *     {
+     *       type: 'npm',
+     *       packages: [
+     *         { name: '@adonisjs/core', startDate: '2020-01-01' }
+     *       ]
+     *     }
+     *   ]
+     * })
+     * ```
+     */
+    ossStats(options: OssStatsOptions): OssStatsLoader<import("@vinejs/vine/types").SchemaTypes>;
     /**
      * Creates a JSON file loader instance.
      *