Package Exports

@contentrain/types-generator
@contentrain/types-generator/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@contentrain/types-generator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@contentrain/types-generator

A tool for automatically generating TypeScript type definitions for Contentrain CMS. This package provides type safety for your Contentrain content models.

Features

🚀 Automatic type generation from model schemas
🔄 Automatic relation type mapping with validation
📦 Full TypeScript support with generics
🎯 CLI tool with debug mode
💪 Comprehensive test coverage
🔍 Watch mode with debounce
🛠️ Custom type transformers
🔧 CI/CD integration
📝 Multiple config file support
🌍 Multi-language support

Installation

# Using npm
npm install -D @contentrain/types-generator

# Using yarn
yarn add -D @contentrain/types-generator

# Using pnpm
pnpm add -D @contentrain/types-generator

CLI Usage

# Basic usage
contentrain-generate

# With custom config file
contentrain-generate --config contentrain.config.js

# With custom directories
contentrain-generate --models ./models --output ./types

# Watch mode with debug output
contentrain-generate --watch --debug

# Help
contentrain-generate --help

Configuration

The generator supports multiple configuration file locations:

contentrain-config.json
.contentrain/config.json
.config/contentrain.json

Example configuration:

{
  // Required: Directory paths
  "modelsDir": "./models",
  "outputDir": "./types",
  "contentDir": "./content",

  // Optional: Type generation options
  "options": {
    // Relation type generation
    "generateRelationTypes": true,
    "includeBaseTypes": true,

    // Type mappings
    "typeMapping": {
      "string[]": "Array<string>",
      "number[]": "Array<number>",
      "date": "Date",
      "media": "MediaFile"
    },

    // Custom type transformers
    "transformers": {
      "date": {
        "type": "Date",
        "imports": ["import { parseISO } from 'date-fns'"],
        "transform": "parseISO"
      },
      "json": {
        "type": "Record<string, any>",
        "transform": "JSON.parse"
      }
    },

    // Output configuration
    "output": {
      "prettier": true,
      "declaration": true,
      "banner": "/* Generated by Contentrain */"
    }
  },

  // Watch mode configuration
  "watch": {
    "enabled": true,
    "debounce": 1000,
    "ignore": ["**/node_modules/**"]
  }
}

Model Schema Example

// models/posts.json
[
  {
    "fieldId": "title",
    "fieldType": "string",
    "componentId": "single-line-text",
    "validations": {
      "required-field": { "value": true }
    }
  },
  {
    "fieldId": "content",
    "fieldType": "string",
    "componentId": "rich-text"
  },
  {
    "fieldId": "author",
    "fieldType": "relation",
    "componentId": "one-to-one",
    "options": {
      "reference": {
        "form": {
          "reference": {
            "value": "authors"
          }
        }
      }
    }
  },
  {
    "fieldId": "categories",
    "fieldType": "relation",
    "componentId": "one-to-many",
    "options": {
      "reference": {
        "form": {
          "reference": {
            "value": "categories"
          }
        }
      }
    }
  }
]

Generated Types Example

// Generated contentrain.d.ts
import type { BaseContentrainType, QueryConfig } from '@contentrain/query';

export interface IPost extends BaseContentrainType {
  title: string;
  content?: string;
  author: string;
  categories: string[];
  _relations?: {
    author: IAuthor;
    categories: ICategory[];
  }
}

export interface IPostQuery extends QueryConfig<
  IPost,
  'en' | 'tr',
  {
    author: IAuthor;
    categories: ICategory;
  }
> {}

Programmatic Usage

import { ContentrainTypesGenerator } from '@contentrain/types-generator';

// Basic usage
const generator = new ContentrainTypesGenerator({
  modelsDir: './models',
  outputDir: './types',
  contentDir: './content'
});

// Generate types
generator.generate();

// With error handling
try {
  const generator = new ContentrainTypesGenerator({
    modelsDir: './models',
    outputDir: './types',
    contentDir: './content'
  });

  generator.generate();
} catch (error) {
  if (error instanceof Error) {
    console.error('Generation failed:', {
      message: error.message,
      cause: error.cause
    });
  }
}

Custom Type Transformers

// Custom date transformer
const dateTransformer = {
  name: 'date',
  match: (field) => field.fieldType === 'date',
  transform: (field) => ({
    type: 'Date',
    imports: ['import { parseISO } from "date-fns"'],
    transform: (value) => `parseISO(${value})`
  })
};

// Custom media transformer
const mediaTransformer = {
  name: 'media',
  match: (field) => field.fieldType === 'media',
  transform: (field) => ({
    type: 'MediaFile',
    imports: ['import type { MediaFile } from "./types"'],
  })
};

// Apply transformers
const generator = new ContentrainTypesGenerator({
  // ... other options
  options: {
    transformers: [dateTransformer, mediaTransformer]
  }
});

Testing

The package includes comprehensive tests. To run them:

# Run tests in watch mode
pnpm test

# Run tests once
pnpm test:run

Example test:

import { ContentrainTypesGenerator } from '@contentrain/types-generator';

describe('Type Generation', () => {
  const generator = new ContentrainTypesGenerator({
    modelsDir: './test/fixtures/models',
    outputDir: './test/output',
    contentDir: './test/fixtures/content'
  });

  it('should generate correct types for models', () => {
    generator.generate();

    const output = fs.readFileSync(
      './test/output/contentrain.d.ts',
      'utf-8'
    );

    expect(output).toContain('export interface IPost');
    expect(output).toContain('_relations?: {');
  });
});

Error Handling

The generator provides detailed error messages for common scenarios:

try {
  generator.generate();
} catch (error) {
  if (error.message.includes('Model directory not found')) {
    // Handle missing directory
  } else if (error.message.includes('Invalid model')) {
    // Handle invalid model schema
  } else if (error.message.includes('Failed to read metadata')) {
    // Handle metadata issues
  }
}

CI/CD Integration

GitHub Actions

name: Generate Types

on:
  push:
    paths:
      - 'models/**'
      - 'content/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'

      - name: Install dependencies
        run: pnpm install

      - name: Generate types
        run: pnpm contentrain-generate

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "chore: update generated types"

GitLab CI

generate-types:
  script:
    - pnpm install
    - pnpm contentrain-generate
  only:
    changes:
      - models/**/*
      - content/**/*
  artifacts:
    paths:
      - types/

API Reference

CLI Options

Options:
  -m, --models <path>   Path to models directory
  -o, --output <path>   Path to output directory
  -c, --content <path>  Path to content directory
  -d, --debug          Enable debug mode
  --watch              Enable watch mode
  -h, --help           Display help
  -v, --version        Display version

Generator Options

interface GeneratorConfig {
  // Required paths
  modelsDir: string;
  outputDir: string;
  contentDir: string;

  // Optional configurations
  options?: {
    generateRelationTypes?: boolean;
    includeBaseTypes?: boolean;
    typeMapping?: Record<string, string>;
    transformers?: TypeTransformer[];
    output?: {
      prettier?: boolean;
      declaration?: boolean;
      banner?: string;
    };
  };

  // Watch mode options
  watch?: {
    enabled?: boolean;
    debounce?: number;
    ignore?: string[];
  };
}

interface TypeTransformer {
  name: string;
  match: (field: FieldMetadata) => boolean;
  transform: (field: FieldMetadata) => {
    type: string;
    imports?: string[];
    transform?: string | ((value: string) => string);
  };
}

License

MIT