@adonisjs/content 1.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# @adonisjs/content
+
+<br />
+
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
+
+## Introduction
+
+A type-safe content management package for AdonisJS that enables you to create validated collections with schema validation and use loaders to load data.
+
+The main goal of this package is to use load data from JSON files for creating documentation websites or blog.
+
+We use this package for all official AdonisJS websites to manage docs, blog posts, Github sponsors data, Github releases, and so on.
+
+**Key Features:**
+
+- **Type-safe collections** with VineJS schema validation
+- **GitHub loaders** for sponsors, releases, and contributors
+- **Custom query methods** for filtering and transforming data
+- **JSON file loading** with validation
+- **Vite integration** for asset path resolution
+
+## Installation
+
+Install the package from npm registry as follows:
+
+```sh
+npm i @adonisjs/content
+```
+
+```sh
+yarn add @adonisjs/content
+```
+
+```sh
+pnpm add @adonisjs/content
+```
+
+## Configuration
+
+The package requires `@adonisjs/core`, `@adonisjs/vite`, and `@vinejs/vine` as peer dependencies. Run the following command to register the `@adonisjs/content/content_provider` to the `adonisrc.ts` file.
+
+```sh
+node ace configure @adonisjs/content
+```
+
+## Usage
+
+### Creating a Collection
+
+Collections are the core building blocks for managing typed content. Create a collection by providing a VineJS schema and a loader:
+
+```ts
+import vine from '@vinejs/vine'
+import app from '@adonisjs/core/services/app'
+import { Collection } from '@adonisjs/content'
+import { loaders } from '@adonisjs/content/loaders'
+
+// Define a schema
+const postSchema = vine.object({
+  title: vine.string(),
+  slug: vine.string(),
+  content: vine.string(),
+  published: vine.boolean(),
+})
+
+// Create a collection with custom views
+const posts = new Collection({
+  schema: vine.array(postSchema),
+  loader: loaders.jsonLoader(app.makePath('data/posts.json')),
+  cache: true,
+  views: {
+    published: (posts) => posts.filter((p) => p.published),
+    findBySlug: (posts, slug: string) => posts.find((p) => p.slug === slug),
+  },
+})
+
+// Query the collection
+const query = await posts.load()
+const allPosts = query.all()
+const publishedPosts = query.published()
+const post = query.findBySlug('hello-world')
+```
+
+### GitHub Sponsors Loader
+
+Fetch and cache GitHub sponsors data:
+
+```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 sponsorSchema = vine.object({
+  id: vine.string(),
+  sponsorLogin: vine.string(),
+  sponsorName: vine.string().nullable().optional(),
+  tierMonthlyPriceInCents: vine.number().nullable().optional(),
+  // ... other fields
+})
+
+const sponsorsLoader = loaders.ghSponsors({
+  login: 'adonisjs',
+  isOrg: true,
+  ghToken: process.env.GITHUB_TOKEN!,
+  outputPath: app.makePath('cache/sponsors.json'),
+  refresh: 'daily',
+})
+
+const sponsors = new Collection({
+  schema: vine.array(sponsorSchema),
+  loader: sponsorsLoader,
+  cache: true,
+})
+
+const query = await sponsors.load()
+const allSponsors = query.all()
+```
+
+### GitHub Releases Loader
+
+Fetch releases from all public repositories in an organization:
+
+```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 releasesLoader = loaders.ghReleases({
+  org: 'adonisjs',
+  ghToken: process.env.GITHUB_TOKEN!,
+  outputPath: app.makePath('cache/releases.json'),
+  refresh: 'daily',
+  filters: {
+    nameDoesntInclude: ['alpha', 'beta', 'rc'],
+    nameIncludes: ['adonis'],
+  },
+})
+
+const releases = new Collection({
+  schema: vine.array(releaseSchema),
+  loader: releasesLoader,
+  cache: true,
+  views: {
+    latest: (releases) => releases.slice(0, 5),
+    byRepo: (releases, repo: string) => releases.filter((r) => r.repo === repo),
+  },
+})
+```
+
+### GitHub Contributors Loader
+
+Aggregate contributors from all public repositories:
+
+```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 contributorsLoader = loaders.ghContributors({
+  org: 'adonisjs',
+  ghToken: process.env.GITHUB_TOKEN!,
+  outputPath: app.makePath('cache/contributors.json'),
+  refresh: 'weekly',
+})
+
+const contributors = new Collection({
+  schema: vine.array(contributorSchema),
+  loader: contributorsLoader,
+  cache: true,
+  views: {
+    top: (contributors, limit: number = 10) =>
+      contributors.sort((a, b) => b.contributions - a.contributions).slice(0, limit),
+  },
+})
+```
+
+### Custom Views
+
+Views allow you to define reusable query methods with full type safety:
+
+```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 postSchema = vine.object({
+  title: vine.string(),
+  slug: vine.string(),
+  published: vine.boolean(),
+  publishedAt: vine.date(),
+})
+
+const posts = new Collection({
+  schema: vine.array(postSchema),
+  loader: loaders.jsonLoader(app.makePath('data/posts.json')),
+  cache: true,
+  views: {
+    // Simple filter
+    published: (posts) => posts.filter((p) => p.published),
+
+    // With parameters
+    findBySlug: (posts, slug: string) => posts.find((p) => p.slug === slug),
+
+    // Complex transformations
+    byYear: (posts) => {
+      const grouped = new Map()
+      for (const post of posts) {
+        const year = new Date(post.publishedAt).getFullYear()
+        if (!grouped.has(year)) grouped.set(year, [])
+        grouped.get(year).push(post)
+      }
+      return grouped
+    },
+  },
+})
+
+const query = await posts.load()
+query.published() // Type-safe!
+query.findBySlug('my-post') // Type-safe!
+query.byYear() // Returns Map<number, Post[]>
+```
+
+### Caching
+
+Collections support intelligent caching with configurable refresh schedules:
+
+- `'daily'`: Refreshes once per day
+- `'weekly'`: Refreshes once per week
+- `'monthly'`: Refreshes once per month
+
+Cached data is stored as JSON with metadata:
+
+```json
+{
+  "lastFetched": "2024-01-15T10:30:00.000Z",
+  "data": [...]
+}
+```
+
+### Vite Integration
+
+Use Vite asset paths in your content:
+
+```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 schema = vine.object({
+  title: vine.string(),
+  image: vine.string().toVitePath(), // Custom VineJS macro
+})
+
+const posts = new Collection({
+  schema: vine.array(schema),
+  loader: loaders.jsonLoader(app.makePath('data/posts.json')),
+  cache: true,
+})
+```
+
+The `toVitePath()` macro converts relative paths to Vite asset paths automatically.
+
+## Contributing
+
+One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believes in the principles of the framework.
+
+We encourage you to read the [contribution guide](https://github.com/adonisjs/.github/blob/main/docs/CONTRIBUTING.md) before contributing to the framework.
+
+## Code of Conduct
+
+In order to ensure that the AdonisJS community is welcoming to all, please review and abide by the [Code of Conduct](https://github.com/adonisjs/.github/blob/main/docs/CODE_OF_CONDUCT.md).
+
+## License
+
+@adonisjs/content is open-sourced software licensed under the [MIT license](LICENSE.md).
+
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/content/checks.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/content/actions/workflows/checks.yml 'Github action'
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: "typescript"
+[npm-image]: https://img.shields.io/npm/v/@adonisjs/content.svg?style=for-the-badge&logo=npm
+[npm-url]: https://npmjs.org/package/@adonisjs/content 'npm'
+[license-image]: https://img.shields.io/npm/l/@adonisjs/content?color=blueviolet&style=for-the-badge
+[license-url]: LICENSE.md 'license'

package/build/chunk-LB6JFRVG.js

@@ -0,0 +1,7 @@
+// src/debug.ts
+import { debuglog } from "util";
+var debug_default = debuglog("adonisjs:content");
+
+export {
+  debug_default
+};

package/build/chunk-ZX3KSI7U.js

@@ -0,0 +1,130 @@
+import {
+  debug_default
+} from "./chunk-LB6JFRVG.js";
+
+// src/collection.ts
+var Collection = class _Collection {
+  static #vite;
+  /** Collection configuration options */
+  #options;
+  /** Cached validated data */
+  #data;
+  #views;
+  /**
+   * Creates a new Collection instance.
+   *
+   * @param options - Configuration options including schema, loader, caching, and views
+   *
+   * @example
+   * ```ts
+   * const posts = new Collection({
+   *   schema: postsSchema,
+   *   loader: fileLoader,
+   *   cache: true,
+   *   views: { published: (posts) => posts.filter(p => p.published) }
+   * })
+   * ```
+   */
+  constructor(options) {
+    this.#options = options;
+  }
+  /**
+   * Factory method to create a new Collection instance.
+   * This is an alternative to using the constructor directly.
+   *
+   * @param options - Configuration options including schema, loader, caching, and views
+   *
+   * @example
+   * ```ts
+   * const posts = Collection.create({
+   *   schema: postsSchema,
+   *   loader: fileLoader,
+   *   cache: true,
+   *   views: { published: (posts) => posts.filter(p => p.published) }
+   * })
+   * ```
+   */
+  static create(options) {
+    return new _Collection(options);
+  }
+  /**
+   * Configures the Vite service instance for resolving asset paths.
+   * This should be called once during application initialization.
+   *
+   * @param vite - The Vite service instance from @adonisjs/vite
+   *
+   * @example
+   * ```ts
+   * Collection.useVite(vite)
+   * ```
+   */
+  static useVite(vite) {
+    this.#vite = vite;
+  }
+  /**
+   * Loads and validates data using the configured loader and schema.
+   * Returns cached data if caching is enabled and data was previously loaded.
+   *
+   * @example
+   * ```ts
+   * const data = await posts.hydrate()
+   * ```
+   */
+  async hydrate() {
+    if (this.#data && this.#views && this.#options.cache) {
+      debug_default("re-using data and views from cache");
+      return {
+        data: this.#data,
+        views: this.#views
+      };
+    }
+    debug_default("computing data");
+    this.#data = await this.#options.loader.load(this.#options.schema, {
+      vite: _Collection.#vite,
+      ...this.#options.validatorMetaData
+    });
+    const views = this.#options.views ?? {};
+    this.#views = Object.keys(views).reduce((result, view) => {
+      ;
+      result[view] = (...args) => views[view](this.#data, ...args);
+      return result;
+    }, {});
+    return {
+      data: this.#data,
+      views: this.#views
+    };
+  }
+  /**
+   * Loads the collection and returns a query interface with all() method
+   * and any configured view methods.
+   *
+   * The returned object includes:
+   * - all(): Returns the complete validated dataset
+   * - Custom view methods as configured in collection options
+   *
+   * @example
+   * ```ts
+   * const query = await posts.load()
+   *
+   * // Get all data
+   * const allPosts = query.all()
+   *
+   * // Use custom view methods
+   * const publishedPosts = query.published()
+   * const post = query.findBySlug('hello-world')
+   * ```
+   */
+  async load() {
+    const { data, views } = await this.hydrate();
+    return {
+      all() {
+        return data;
+      },
+      ...views
+    };
+  }
+};
+
+export {
+  Collection
+};

package/build/configure.d.ts

@@ -0,0 +1,5 @@
+import type Configure from '@adonisjs/core/commands/configure';
+/**
+ * Configures the package
+ */
+export declare function configure(command: Configure): Promise<void>;

package/build/index.d.ts

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

package/build/index.js

@@ -0,0 +1,16 @@
+import {
+  Collection
+} from "./chunk-ZX3KSI7U.js";
+import "./chunk-LB6JFRVG.js";
+
+// configure.ts
+async function configure(command) {
+  const codemods = await command.createCodemods();
+  await codemods.updateRcFile((rcFile) => {
+    rcFile.addProvider("@adonisjs/content/content_provider");
+  });
+}
+export {
+  Collection,
+  configure
+};

package/build/providers/content_provider.d.ts

@@ -0,0 +1,46 @@
+import { type ApplicationService } from '@adonisjs/core/types';
+declare module '@vinejs/vine' {
+    interface VineString {
+        /**
+         * Converts a relative path to a Vite asset path.
+         * This method transforms the path using Vite's asset resolution system.
+         */
+        toVitePath(): this;
+        /**
+         * Converts a relative path to an absolute file system path.
+         * The path is resolved relative to the menu file root directory.
+         */
+        toAbsolutePath(): this;
+    }
+}
+/**
+ * Service provider for the AdonisJS content package.
+ *
+ * This provider sets up the content collection system and integrates
+ * with Vite for asset handling if Vite is available in the application.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   providers: [
+ *     () => import('@adonisjs/content/content_provider')
+ *   ]
+ * }
+ * ```
+ */
+export default class ContentProvider {
+    protected app: ApplicationService;
+    /**
+     * Creates a new instance of the content provider.
+     *
+     * @param app - The AdonisJS application service instance
+     */
+    constructor(app: ApplicationService);
+    /**
+     * Boots the content provider during the application boot phase.
+     *
+     * If Vite is registered in the container, this method configures
+     * the Collection class to use Vite's asset resolution system.
+     */
+    boot(): Promise<void>;
+}

package/build/providers/content_provider.js

@@ -0,0 +1,45 @@
+import {
+  Collection
+} from "../chunk-ZX3KSI7U.js";
+import "../chunk-LB6JFRVG.js";
+
+// providers/content_provider.ts
+import { resolve } from "path";
+import vine, { VineString } from "@vinejs/vine";
+var toVitePath = vine.createRule(function vitePath(value, _, field) {
+  field.mutate(field.meta.vite.assetPath(value), field);
+});
+var toAbsolutePath = vine.createRule(function absolutePath(value, _, field) {
+  field.mutate(resolve(field.meta.menuFileRoot, value), field);
+});
+VineString.macro("toVitePath", function() {
+  return this.use(toVitePath());
+});
+VineString.macro("toAbsolutePath", function() {
+  return this.use(toAbsolutePath());
+});
+var ContentProvider = class {
+  /**
+   * Creates a new instance of the content provider.
+   *
+   * @param app - The AdonisJS application service instance
+   */
+  constructor(app) {
+    this.app = app;
+  }
+  /**
+   * Boots the content provider during the application boot phase.
+   *
+   * If Vite is registered in the container, this method configures
+   * the Collection class to use Vite's asset resolution system.
+   */
+  async boot() {
+    if (this.app.container.hasBinding("vite")) {
+      const vite = await this.app.container.make("vite");
+      Collection.useVite(vite);
+    }
+  }
+};
+export {
+  ContentProvider as default
+};

package/build/src/collection.d.ts

@@ -0,0 +1,112 @@
+import { type Vite } from '@adonisjs/vite';
+import { type Infer, type SchemaTypes } from '@vinejs/vine/types';
+import { type CollectionOptions, type ViewFn, type ViewsToQueryMethods } from './types.js';
+/**
+ * Manages a collection of data with schema validation and custom view functions.
+ *
+ * The Collection class provides a way to load, validate, and query structured data
+ * using VineJS schemas. It supports caching and custom view functions for data
+ * transformations and queries.
+ *
+ * @example
+ * ```ts
+ * const posts = new Collection({
+ *   schema: postsSchema,
+ *   loader: fileLoader,
+ *   cache: true,
+ *   views: {
+ *     published: (posts) => posts.filter(p => p.published),
+ *     findBySlug: (posts, slug) => posts.find(p => p.slug === slug)
+ *   }
+ * })
+ *
+ * const query = await posts.load()
+ * const allPosts = query.all()
+ * const publishedPosts = query.published()
+ * const post = query.findBySlug('hello-world')
+ * ```
+ */
+export declare class Collection<Schema extends SchemaTypes, Views extends Record<string, ViewFn<Schema, any, any>>> {
+    #private;
+    /**
+     * Creates a new Collection instance.
+     *
+     * @param options - Configuration options including schema, loader, caching, and views
+     *
+     * @example
+     * ```ts
+     * const posts = new Collection({
+     *   schema: postsSchema,
+     *   loader: fileLoader,
+     *   cache: true,
+     *   views: { published: (posts) => posts.filter(p => p.published) }
+     * })
+     * ```
+     */
+    constructor(options: CollectionOptions<Schema, Views>);
+    /**
+     * Factory method to create a new Collection instance.
+     * This is an alternative to using the constructor directly.
+     *
+     * @param options - Configuration options including schema, loader, caching, and views
+     *
+     * @example
+     * ```ts
+     * const posts = Collection.create({
+     *   schema: postsSchema,
+     *   loader: fileLoader,
+     *   cache: true,
+     *   views: { published: (posts) => posts.filter(p => p.published) }
+     * })
+     * ```
+     */
+    static create<Schema extends SchemaTypes, Views extends Record<string, ViewFn<Schema, any, any>>>(options: CollectionOptions<Schema, Views>): Collection<Schema, Views>;
+    /**
+     * Configures the Vite service instance for resolving asset paths.
+     * This should be called once during application initialization.
+     *
+     * @param vite - The Vite service instance from @adonisjs/vite
+     *
+     * @example
+     * ```ts
+     * Collection.useVite(vite)
+     * ```
+     */
+    static useVite(vite: Vite): void;
+    /**
+     * Loads and validates data using the configured loader and schema.
+     * Returns cached data if caching is enabled and data was previously loaded.
+     *
+     * @example
+     * ```ts
+     * const data = await posts.hydrate()
+     * ```
+     */
+    hydrate(): Promise<{
+        data: Infer<Schema> | undefined;
+        views: ViewsToQueryMethods<Views>;
+    }>;
+    /**
+     * Loads the collection and returns a query interface with all() method
+     * and any configured view methods.
+     *
+     * The returned object includes:
+     * - all(): Returns the complete validated dataset
+     * - Custom view methods as configured in collection options
+     *
+     * @example
+     * ```ts
+     * const query = await posts.load()
+     *
+     * // Get all data
+     * const allPosts = query.all()
+     *
+     * // Use custom view methods
+     * const publishedPosts = query.published()
+     * const post = query.findBySlug('hello-world')
+     * ```
+     */
+    load(): Promise<{
+        all(): Infer<Schema>;
+    } & ViewsToQueryMethods<Views>>;
+}

package/build/src/debug.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Debug logger for the @adonisjs/content package.
+ * Enable debug logs by setting NODE_DEBUG=adonisjs:content environment variable.
+ *
+ * @example
+ * ```ts
+ * debug('loading file "%s"', filePath)
+ * ```
+ */
+declare const _default: import("util").DebugLogger;
+export default _default;