@adonisjs/content 1.1.0

package/build/src/types.d.ts

@@ -0,0 +1,280 @@
+import { type Infer, type SchemaTypes } from '@vinejs/vine/types';
+/**
+ * Contract for loading and validating content data using a VineJS schema.
+ *
+ * @example
+ * ```ts
+ * const loader: LoaderContract<typeof mySchema> = {
+ *   async load(schema) {
+ *     const data = await fetchData()
+ *     return vine.validate({ schema, data })
+ *   }
+ * }
+ * ```
+ */
+export interface LoaderContract<Schema extends SchemaTypes> {
+    /**
+     * Loads and validates data against the provided schema.
+     *
+     * @param schema - VineJS schema to validate the loaded data against
+     */
+    load(schema: Schema, validatorMetaData?: any): Promise<Infer<Schema>>;
+}
+/**
+ * A function type that transforms or queries collection data.
+ *
+ * @example
+ * ```ts
+ * const filterByStatus: ViewFn<typeof schema, [string], Item[]> = (data, status) => {
+ *   return data.filter(item => item.status === status)
+ * }
+ * ```
+ */
+export type ViewFn<Schema extends SchemaTypes, Args extends any[], Result> = (input: Infer<Schema>, ...args: Args) => Result;
+/**
+ * Transforms a record of view functions into query method signatures.
+ * Extracts the arguments and return type from each ViewFn to create method signatures.
+ *
+ * @example
+ * ```ts
+ * type Views = {
+ *   filterByStatus: ViewFn<typeof schema, [string], Item[]>
+ *   findById: ViewFn<typeof schema, [number], Item | undefined>
+ * }
+ *
+ * type Methods = ViewsToQueryMethods<Views>
+ * // Results in:
+ * // {
+ * //   filterByStatus: (status: string) => Item[]
+ * //   findById: (id: number) => Item | undefined
+ * // }
+ * ```
+ */
+export type ViewsToQueryMethods<Views> = {
+    [K in keyof Views]: Views[K] extends ViewFn<any, infer Args, infer Result> ? (...args: Args) => Result : never;
+};
+/**
+ * Configuration options for creating a Collection instance.
+ *
+ * @example
+ * ```ts
+ * const options: CollectionOptions<typeof postsSchema, typeof postViews> = {
+ *   schema: postsSchema,
+ *   loader: fileLoader,
+ *   cache: true,
+ *   views: {
+ *     published: (posts) => posts.filter(p => p.published),
+ *     findBySlug: (posts, slug) => posts.find(p => p.slug === slug)
+ *   }
+ * }
+ * ```
+ */
+export type CollectionOptions<Schema extends SchemaTypes, Views extends {
+    [name: string]: ViewFn<NoInfer<Schema>, any, any>;
+}> = {
+    validatorMetaData?: any;
+    /** VineJS schema for validating loaded data */
+    schema: Schema;
+    /** Loader implementation for fetching and validating data */
+    loader: LoaderContract<NoInfer<Schema>>;
+    /** Whether to cache loaded data after first hydration */
+    cache: boolean;
+    /** Optional view functions for querying/transforming the collection */
+    views?: Views;
+};
+/**
+ * Configuration options for loading GitHub releases from an organization.
+ *
+ * @example
+ * ```ts
+ * const options: GithubReleasesOptions = {
+ *   org: 'adonisjs',
+ *   ghToken: process.env.GITHUB_TOKEN,
+ *   outputPath: './cache/releases.json',
+ *   refresh: 'daily',
+ *   filters: {
+ *     nameDoesntInclude: ['alpha', 'beta']
+ *   }
+ * }
+ * ```
+ */
+export type GithubReleasesOptions = {
+    /** GitHub organization name */
+    org: string;
+    /** GitHub personal access token for authentication */
+    ghToken: string;
+    /** Path where cached data will be stored */
+    outputPath: string;
+    /** How often to refresh the cached data */
+    refresh: 'daily' | 'weekly' | 'monthly';
+    /** Optional filters to include/exclude releases by name patterns */
+    filters?: {
+        /** Array of substrings that release names must contain */
+        nameIncludes?: string[];
+        /** Array of substrings that release names must not contain */
+        nameDoesntInclude?: string[];
+    };
+};
+/**
+ * Represents a GitHub sponsor with their details and sponsorship information.
+ *
+ * @example
+ * ```ts
+ * const sponsor: GithubSponsor = {
+ *   id: 'sp_123',
+ *   createdAt: '2023-01-15T10:00:00Z',
+ *   privacyLevel: 'PUBLIC',
+ *   tierName: 'Gold Sponsor',
+ *   tierMonthlyPriceInCents: 10000,
+ *   sponsorType: 'User',
+ *   sponsorLogin: 'johndoe',
+ *   sponsorName: 'John Doe',
+ *   sponsorAvatarUrl: 'https://avatars.githubusercontent.com/u/123',
+ *   sponsorUrl: 'https://github.com/johndoe'
+ * }
+ * ```
+ */
+export type GithubSponsor = {
+    /** Unique identifier for the sponsorship */
+    id: string;
+    /** ISO 8601 timestamp when the sponsorship was created */
+    createdAt: string;
+    /** Privacy level of the sponsorship (PUBLIC, PRIVATE, etc.) */
+    privacyLevel: string | null;
+    /** Name of the sponsorship tier */
+    tierName: string | null;
+    /** Monthly price of the tier in cents */
+    tierMonthlyPriceInCents: number | null;
+    /** Type of sponsor entity: "User" or "Organization" */
+    sponsorType: string;
+    /** GitHub username of the sponsor */
+    sponsorLogin: string;
+    /** Display name of the sponsor */
+    sponsorName?: string | null;
+    /** Avatar URL of the sponsor */
+    sponsorAvatarUrl?: string | null;
+    /** Profile URL of the sponsor */
+    sponsorUrl?: string | null;
+};
+/**
+ * Configuration options for loading GitHub sponsors for a user or organization.
+ *
+ * @example
+ * ```ts
+ * const options: GithubSponsorsOptions = {
+ *   login: 'adonisjs',
+ *   isOrg: true,
+ *   ghToken: process.env.GITHUB_TOKEN,
+ *   outputPath: './cache/sponsors.json',
+ *   refresh: 'daily'
+ * }
+ * ```
+ */
+export type GithubSponsorsOptions = {
+    /** GitHub username or organization name */
+    login: string;
+    /** Whether the login is an organization (true) or user (false) */
+    isOrg: boolean;
+    /** GitHub personal access token for authentication */
+    ghToken: string;
+    /** Path where cached sponsors will be stored */
+    outputPath: string;
+    /** How often to refresh the cached data */
+    refresh: 'daily' | 'weekly' | 'monthly';
+};
+/**
+ * Represents a GitHub release with its metadata.
+ *
+ * @example
+ * ```ts
+ * const release: GithubRelease = {
+ *   name: 'v5.0.0',
+ *   tagName: 'v5.0.0',
+ *   publishedAt: '2023-12-01T10:00:00Z',
+ *   url: 'https://github.com/adonisjs/core/releases/tag/v5.0.0',
+ *   description: 'Major release with breaking changes'
+ * }
+ * ```
+ */
+export type GithubRelease = {
+    /** Name of the release */
+    name: string;
+    /** Git tag name associated with the release */
+    tagName: string;
+    /** ISO 8601 timestamp when the release was published */
+    publishedAt: string;
+    /** URL to the release page on GitHub */
+    url: string;
+    /** Markdown description/notes for the release */
+    description: string | null;
+};
+/**
+ * GitHub release with repository information.
+ * Extends GithubRelease to include the repository name.
+ *
+ * @example
+ * ```ts
+ * const release: GithubReleaseWithRepo = {
+ *   repo: 'core',
+ *   name: 'v5.0.0',
+ *   tagName: 'v5.0.0',
+ *   publishedAt: '2023-12-01T10:00:00Z',
+ *   url: 'https://github.com/adonisjs/core/releases/tag/v5.0.0',
+ *   description: 'Major release with breaking changes'
+ * }
+ * ```
+ */
+export type GithubReleaseWithRepo = GithubRelease & {
+    /** Name of the repository this release belongs to */
+    repo: string;
+};
+/**
+ * Configuration options for loading GitHub contributors from an organization.
+ *
+ * @example
+ * ```ts
+ * const options: GithubContributorsOptions = {
+ *   org: 'adonisjs',
+ *   ghToken: process.env.GITHUB_TOKEN,
+ *   outputPath: './cache/contributors.json',
+ *   refresh: 'weekly'
+ * }
+ * ```
+ */
+export type GithubContributorsOptions = {
+    /** GitHub organization name */
+    org: string;
+    /** GitHub personal access token for authentication */
+    ghToken: string;
+    /** Path where cached contributors will be stored */
+    outputPath: string;
+    /** How often to refresh the cached data */
+    refresh: 'daily' | 'weekly' | 'monthly';
+};
+/**
+ * Represents a GitHub contributor with their profile information and contribution count.
+ * This matches the shape returned by GitHub REST API /contributors endpoint.
+ *
+ * @example
+ * ```ts
+ * const contributor: GithubContributorNode = {
+ *   login: 'thetutlage',
+ *   id: 103858,
+ *   avatar_url: 'https://avatars.githubusercontent.com/u/103858',
+ *   html_url: 'https://github.com/thetutlage',
+ *   contributions: 250
+ * }
+ * ```
+ */
+export type GithubContributorNode = {
+    /** GitHub username of the contributor */
+    login: string;
+    /** Unique GitHub user ID */
+    id?: number;
+    /** Avatar URL of the contributor */
+    avatar_url?: string | null;
+    /** Profile URL of the contributor */
+    html_url?: string | null;
+    /** Number of contributions made to the repository */
+    contributions: number;
+};

package/build/src/utils.d.ts

@@ -0,0 +1,82 @@
+import { type GithubSponsor, type GithubReleasesOptions, type GithubReleaseWithRepo, type GithubSponsorsOptions, type GithubContributorNode, type GithubContributorsOptions } from './types.ts';
+/**
+ * Fetches all sponsors for a GitHub user or organization using GraphQL API.
+ * Handles pagination automatically to retrieve all sponsors across multiple requests.
+ *
+ * @param options - Configuration options for fetching sponsors
+ * @param options.login - GitHub username or organization name
+ * @param options.isOrg - Whether the login is an organization (true) or user (false)
+ * @param options.ghToken - GitHub personal access token for authentication
+ *
+ * @example
+ * ```ts
+ * const sponsors = await fetchAllSponsors({
+ *   login: 'adonisjs',
+ *   isOrg: true,
+ *   ghToken: process.env.GITHUB_TOKEN
+ * })
+ * ```
+ */
+export declare function fetchAllSponsors({ login, isOrg, ghToken, }: GithubSponsorsOptions): Promise<GithubSponsor[]>;
+/**
+ * Fetches all releases from public repositories of a GitHub organization.
+ * Handles pagination and supports filtering releases by name patterns.
+ *
+ * @param options - Configuration options for fetching releases
+ * @param options.org - GitHub organization name
+ * @param options.ghToken - GitHub personal access token for authentication
+ * @param options.filters - Optional filters to include/exclude releases by name patterns
+ * @param options.filters.nameIncludes - Array of substrings that release names must contain
+ * @param options.filters.nameDoesntInclude - Array of substrings that release names must not contain
+ *
+ * @example
+ * ```ts
+ * const releases = await fetchReleases({
+ *   org: 'adonisjs',
+ *   ghToken: process.env.GITHUB_TOKEN,
+ *   filters: {
+ *     nameIncludes: ['v'],
+ *     nameDoesntInclude: ['alpha', 'beta']
+ *   }
+ * })
+ * ```
+ */
+export declare function fetchReleases({ org, ghToken, filters, }: GithubReleasesOptions): Promise<GithubReleaseWithRepo[]>;
+/**
+ * Fetches all contributors from all public, non-archived repositories in a GitHub organization.
+ * Uses the GitHub REST API with pagination to retrieve contributors from each repository.
+ * Handles errors gracefully by logging warnings for failed repositories.
+ *
+ * @param options - Configuration options for fetching contributors
+ * @param options.org - GitHub organization name
+ * @param options.ghToken - GitHub personal access token for authentication
+ *
+ * @example
+ * ```ts
+ * const contributors = await fetchContributorsForOrg({
+ *   org: 'adonisjs',
+ *   ghToken: process.env.GITHUB_TOKEN,
+ *   outputPath: './cache/contributors.json',
+ *   refresh: 'weekly'
+ * })
+ * ```
+ */
+export declare function fetchContributorsForOrg({ org, ghToken, }: GithubContributorsOptions): Promise<GithubContributorNode[]>;
+/**
+ * Merges two arrays by removing duplicates based on a specified key.
+ * Items from the existing array are preserved, and only new unique items
+ * from the fresh array are added.
+ *
+ * @param existing - The existing array to merge into
+ * @param fresh - The new array containing potentially duplicate items
+ * @param key - The property key to use for identifying duplicates
+ *
+ * @example
+ * ```ts
+ * const existing = [{ id: 1, name: 'foo' }, { id: 2, name: 'bar' }]
+ * const fresh = [{ id: 2, name: 'bar' }, { id: 3, name: 'baz' }]
+ * const merged = mergeArrays(existing, fresh, 'id')
+ * // Result: [{ id: 1, name: 'foo' }, { id: 2, name: 'bar' }, { id: 3, name: 'baz' }]
+ * ```
+ */
+export declare function mergeArrays<T, K extends keyof T>(existing: T[], fresh: T[], key: K): T[];

package/package.json

@@ -0,0 +1,146 @@
+{
+  "name": "@adonisjs/content",
+  "description": "Content management for AdonisJS with schema validation, GitHub loaders, and custom queries",
+  "version": "1.1.0",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "type": "module",
+  "files": [
+    "build",
+    "!build/bin",
+    "!build/tests"
+  ],
+  "main": "build/index.js",
+  "exports": {
+    "./loaders": "./build/loaders/main.js",
+    "./types": "./build/types.js",
+    "./content_provider": "./build/providers/content_provider.js",
+    ".": "./build/index.js"
+  },
+  "scripts": {
+    "pretest": "npm run lint",
+    "test": "c8 npm run quick:test",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "precompile": "npm run lint",
+    "compile": "tsup-node && tsc --emitDeclarationOnly --declaration",
+    "build": "npm run compile",
+    "version": "npm run build",
+    "prepublishOnly": "npm run build",
+    "release": "release-it",
+    "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/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",
+    "@poppinss/ts-exec": "^1.4.1",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/node": "^24.10.1",
+    "@vinejs/vine": "^4.1.0",
+    "c8": "^10.1.3",
+    "eslint": "^9.39.1",
+    "prettier": "^3.6.2",
+    "release-it": "^19.0.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@octokit/graphql": "^9.0.3",
+    "@octokit/rest": "^22.0.1",
+    "dayjs": "^1.11.19"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^7.0.0-next.10",
+    "@adonisjs/assembler": "^8.0.0-next.19",
+    "@adonisjs/vite": "^5.1.0-next.1",
+    "@vinejs/vine": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/assembler": {
+      "optional": true
+    }
+  },
+  "homepage": "https://github.com/adonisjs/content#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adonisjs/content.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adonisjs/content/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "content",
+    "collection",
+    "schema",
+    "validation",
+    "github",
+    "sponsors",
+    "contributors",
+    "releases",
+    "cms"
+  ],
+  "author": "Harminder Virk <virk@adonisjs.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "tsup": {
+    "entry": [
+      "index.ts",
+      "providers/content_provider.ts",
+      "src/loaders/main.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "dts": false,
+    "sourcemap": false,
+    "target": "esnext"
+  },
+  "release-it": {
+    "git": {
+      "requireCleanWorkingDir": true,
+      "requireUpstream": true,
+      "commitMessage": "chore(release): ${version}",
+      "tagAnnotation": "v${version}",
+      "push": true,
+      "tagName": "v${version}"
+    },
+    "github": {
+      "release": true
+    },
+    "npm": {
+      "publish": true,
+      "skipChecks": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "exclude": [
+      "tests/**"
+    ]
+  },
+  "prettier": "@adonisjs/prettier-config"
+}