@adonisjs/content 1.3.0 → 1.5.0

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

@@ -0,0 +1,66 @@
+import { type SchemaTypes } from '@vinejs/vine/types';
+import type { OssStatsOptions, LoaderContract } from '../types.ts';
+/**
+ * A loader that aggregates open source statistics from multiple sources.
+ * Supports GitHub organization stars and npm package download counts.
+ * Provides caching and automatic refresh based on a schedule.
+ *
+ * @example
+ * ```ts
+ * const loader = new OssStatsLoader({
+ *   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' }
+ *       ]
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+export declare class OssStatsLoader<Schema extends SchemaTypes> implements LoaderContract<Schema> {
+    #private;
+    /**
+     * Creates a new OSS stats loader instance.
+     *
+     * @param options - Configuration options for loading OSS statistics
+     *
+     * @example
+     * ```ts
+     * const loader = new OssStatsLoader({
+     *   outputPath: './cache/oss-stats.json',
+     *   refresh: 'weekly',
+     *   sources: [
+     *     {
+     *       type: 'github',
+     *       org: 'adonisjs',
+     *       ghToken: process.env.GITHUB_TOKEN
+     *     }
+     *   ]
+     * })
+     * ```
+     */
+    constructor(options: OssStatsOptions);
+    /**
+     * Loads and validates OSS statistics data.
+     * Uses cached data if available and not expired, otherwise fetches fresh data
+     * from configured sources and updates the cache.
+     *
+     * @param schema - VineJS schema to validate the statistics data against
+     * @param metadata - Optional metadata to pass to the validator
+     *
+     * @example
+     * ```ts
+     * const stats = await loader.load(ossStatsSchema)
+     * ```
+     */
+    load(schema: Schema, metadata?: any): Promise<import("@vinejs/vine/types").Infer<Schema>>;
+}

package/build/src/types.d.ts

@@ -251,6 +251,67 @@ export type GithubContributorsOptions = {
     /** How often to refresh the cached data */
     refresh: 'daily' | 'weekly' | 'monthly';
 };
+/**
+ * Configuration options for loading and caching open source statistics from multiple sources.
+ * Supports aggregating data from GitHub organizations and npm package downloads.
+ *
+ * @example
+ * ```ts
+ * const options: OssStatsOptions = {
+ *   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' },
+ *         { name: '@adonisjs/lucid', startDate: '2020-01-01' }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export type OssStatsOptions = {
+    /** Path where cached stats will be stored */
+    outputPath: string;
+    /** How often to refresh the cached data */
+    refresh: 'daily' | 'weekly' | 'monthly';
+    /** Array of data sources to aggregate statistics from */
+    sources: ({
+        /** Source type: GitHub organization statistics */
+        type: 'github';
+        /** GitHub organization name */
+        org: string;
+        /** GitHub personal access token for authentication */
+        ghToken: string;
+    } | {
+        /** Source type: npm package download statistics */
+        type: 'npm';
+        /** Array of npm packages with their tracking start dates */
+        packages: {
+            name: string;
+            startDate: string;
+        }[];
+    } | (() => Promise<{
+        key: string;
+        count: number;
+    }>))[];
+};
+/**
+ * Type representing the aggregated open source statistics
+ */
+export type OssStats = {
+    /** Total GitHub stars across all sources */
+    stars: number;
+    /** Total npm package downloads across all sources */
+    installs: number;
+} & Record<string, number>;
 /**
  * Represents a GitHub contributor with their profile information and contribution count.
  * This matches the shape returned by GitHub REST API /contributors endpoint.

package/build/src/utils.d.ts

@@ -68,3 +68,101 @@ export declare function fetchContributorsForOrg({ org, ghToken, }: GithubContrib
  * ```
  */
 export declare function mergeArrays<T, K extends keyof T>(existing: T[], fresh: T[], key: K): T[];
+/**
+ * Aggregates total npm package downloads across multiple packages from their start dates to today.
+ * Fetches download statistics from the npm registry API for each package and sums them up.
+ *
+ * @param packages - Array of package objects containing name and start date for tracking downloads
+ *
+ * @example
+ * ```ts
+ * const total = await aggregateInstalls([
+ *   { name: '@adonisjs/core', startDate: '2020-01-01' },
+ *   { name: '@adonisjs/lucid', startDate: '2020-01-01' }
+ * ])
+ * console.log(`Total downloads: ${total}`)
+ * ```
+ */
+export declare function aggregateInstalls(packages: {
+    name: string;
+    startDate: string;
+}[]): Promise<number>;
+/**
+ * Aggregates the total number of GitHub stars across all public, non-archived repositories
+ * in a GitHub organization. Uses pagination to fetch all repositories and sum their stars.
+ *
+ * @param options - Configuration object containing organization name and GitHub token
+ *
+ * @example
+ * ```ts
+ * const stars = await aggregateStars({
+ *   org: 'adonisjs',
+ *   ghToken: process.env.GITHUB_TOKEN
+ * })
+ * console.log(`Total stars: ${stars}`)
+ * ```
+ */
+export declare function aggregateStars({ org, ghToken, }: {
+    org: string;
+    ghToken: string;
+}): Promise<number>;
+/**
+ * Creates a cache manager for storing and retrieving data with time-based expiration.
+ * The cache is persisted to disk as JSON and automatically expires based on the configured refresh interval.
+ *
+ * @param options - Configuration object for the cache
+ * @param options.key - The key name for storing the cached data in the JSON file
+ * @param options.outputPath - The file system path where the cache file will be stored
+ * @param options.contents - The initial contents (not used in the implementation, appears to be unused parameter)
+ * @param options.refresh - The refresh interval: 'daily', 'weekly', or 'monthly'
+ *
+ * @example
+ * ```ts
+ * const sponsorsCache = createCache({
+ *   key: 'sponsors',
+ *   outputPath: './cache/sponsors.json',
+ *   contents: [],
+ *   refresh: 'daily'
+ * })
+ *
+ * // Try to get cached data
+ * const cachedSponsors = await sponsorsCache.get()
+ * if (!cachedSponsors) {
+ *   // Cache expired or doesn't exist, fetch fresh data
+ *   const freshSponsors = await fetchAllSponsors({ ... })
+ *   await sponsorsCache.put(freshSponsors)
+ * }
+ * ```
+ */
+export declare function createCache<T>({ key, outputPath, refresh, }: {
+    key: string;
+    outputPath: string;
+    refresh: 'daily' | 'weekly' | 'monthly';
+}): {
+    /**
+     * 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')
+     * }
+     * ```
+     */
+    get(): Promise<any>;
+    /**
+     * 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)
+     * ```
+     */
+    put(contents: T): Promise<T>;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adonisjs/content",
   "description": "Content management for AdonisJS with schema validation, GitHub loaders, and custom queries",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -33,24 +33,24 @@
     "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts"
   },
   "devDependencies": {
-    "@adonisjs/assembler": "^8.0.0-next.19",
-    "@adonisjs/core": "^7.0.0-next.10",
+    "@adonisjs/assembler": "^8.0.0-next.27",
+    "@adonisjs/core": "^7.0.0-next.16",
     "@adonisjs/eslint-config": "^3.0.0-next.4",
     "@adonisjs/prettier-config": "^1.4.5",
     "@adonisjs/tsconfig": "^2.0.0-next.3",
-    "@adonisjs/vite": "^5.1.0-next.1",
-    "@japa/assert": "^4.1.1",
-    "@japa/expect-type": "^2.0.3",
-    "@japa/file-system": "^2.3.2",
-    "@japa/runner": "^4.4.0",
+    "@adonisjs/vite": "^5.1.0-next.2",
+    "@japa/assert": "^4.2.0",
+    "@japa/expect-type": "^2.0.4",
+    "@japa/file-system": "^3.0.0",
+    "@japa/runner": "^5.0.0",
     "@poppinss/ts-exec": "^1.4.1",
-    "@release-it/conventional-changelog": "^10.0.1",
-    "@types/node": "^24.10.1",
-    "@vinejs/vine": "^4.1.0",
+    "@release-it/conventional-changelog": "^10.0.4",
+    "@types/node": "^25.0.3",
+    "@vinejs/vine": "^4.2.0",
     "c8": "^10.1.3",
-    "eslint": "^9.39.1",
-    "prettier": "^3.6.2",
-    "release-it": "^19.0.6",
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4",
+    "release-it": "^19.2.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
@@ -60,8 +60,8 @@
     "dayjs": "^1.11.19"
   },
   "peerDependencies": {
-    "@adonisjs/core": "^7.0.0-next.10",
     "@adonisjs/assembler": "^8.0.0-next.19",
+    "@adonisjs/core": "^7.0.0-next.10",
     "@adonisjs/vite": "^5.1.0-next.1",
     "@vinejs/vine": "^4.1.0"
   },