Repack: Schema-Driven Code Generation

Welcome to Repack! 🚀 This powerful tool lets you define your data models once and generate code for multiple languages and platforms. Think of it as a universal translator for your data structures - write your schema in Repack's simple syntax, create blueprints for your target languages, and let Repack handle the rest.

Quick Start

Here's a taste of what Repack can do:

1. Define your schema (.repack file):

enum UserType {
    Admin
    User  
    Guest
}

struct User @users {
    id uuid
    name string
    email string
    user_type UserType
    created_date datetime
}

2. Choose your outputs:

output typescript @src/types;
output postgres @database;

3. Get generated code automatically!

Table of Contents

• Core Concepts
• Repack Language Reference
  • Data Types
  • Structs
  • Enums
  • Fields
  • Queries
  • Inheritance
  • Snippets
• Blueprint Language Reference
  • Template Syntax
  • Variables
  • Control Flow
  • File Generation
• Complete Examples
• Best Practices

Core Concepts

Repack consists of two complementary languages:

• Repack Schema Language: Define your data structures, relationships, and database queries
• Blueprint Template Language: Create templates that generate code from your schemas

The workflow is simple:

1. Write .repack files defining your data models
2. Use existing blueprints or create custom .blueprint templates
3. Run Repack to generate code in any language you need

Repack Language Reference

Data Types

Repack provides a comprehensive type system with built-in primitives and custom types.

Primitive Types

Type Modifiers

Examples:

struct Product {
    id uuid                    // Required UUID
    name string               // Required string
    description string?       // Optional string
    tags string[]            // Required array of strings
    images string[]?         // Optional array of strings
    price float64            // Required number
}

Structs

Structs are the core building blocks representing entities in your system.

Basic Syntax

struct EntityName [@table_name] [: ParentStruct] [#category]* {
    // fields, queries, and functions
}

Struct Components

Complete Example:

struct User @users : BaseEntity #model #api {
    name string
    email string  
    is_admin boolean
    
    query GetByEmail(_email string) = "SELECT $fields FROM $locations WHERE $email = $_email" : one
}

Enums

Enums define fixed sets of possible values.

Basic Syntax

enum EnumName [#category]* {
    ValueA ["custom_string"]
    ValueB ["another_string"]
    ValueC
}

Enum Features

Examples:

// Simple enum
enum Status {
    Active
    Inactive
    Pending
}

// Enum with custom values
enum UserRole #auth {
    Admin "ADMIN_USER"
    Editor "EDITOR_USER"  
    Viewer "VIEWER_USER"
}

Fields

Fields define the properties of your structs.

Field Types

Field Functions

Fields can have attached functions that modify behavior:

struct User {
    id uuid db:pk                                    // Database primary key
    email string db:unique                           // Database unique constraint  
    full_name string db:as("first_name || ' ' || last_name")  // Computed field
    created_date datetime db:default("NOW()")       // Default value
}

Common Field Functions:

Queries

Repack supports three types of queries for database operations.

Query Types Comparison

Query Interpolation Variables

Repack provides powerful query interpolation:

Query Examples:

struct User @users {
    id uuid
    name string
    email string
    
    // Manual query
    query GetByEmail(_email string) = "SELECT $fields FROM $locations WHERE $email = $_email" : one
    
    // Auto insert
    insert CreateUser(id, name, email) : one
    
    // Auto update  
    update UpdateEmail(_id uuid, _email string) = "SET $email = $_email WHERE $id = $_id" : one
}

Inheritance

Repack supports single inheritance for sharing common fields.

struct BaseEntity {
    id uuid
    created_date datetime
    updated_date datetime
}

struct User : BaseEntity @users {
    name string
    email string
    
    // Reference parent field
    user_id super.id
}

Inheritance Rules:

• Child inherits parent's table name (if any)
• Use super.field to reference parent fields
• Only single inheritance is supported

Snippets

Snippets provide reusable field collections.

Defining Snippets

snippet Timestamps {
    created_date datetime db:default("NOW()")
    updated_date datetime db:default("NOW()")
}

snippet Identifiable {
    id uuid db:pk
}

Using Snippets

struct User @users {
    !Identifiable    // Includes id field
    !Timestamps      // Includes created_date and updated_date
    
    name string
    email string
}

Key Benefits:

• Reduce duplication across structs
• Ensure consistency of common patterns
• Easy to maintain shared functionality

Advanced Features

Joins

Define relationships between structs for complex queries:

struct UserWithTokens : User {
    join(t Token) = "INNER JOIN $name ON $super.id = $t.user_id"
    
    token_value t.token_value
    
    query GetUserTokens(_id uuid) = "SELECT $fields FROM $locations WHERE $user_id = $_id" : many
}

Categories and Filtering

Use categories to organize and filter your schema:

struct User #model #api {
    // This struct has both 'model' and 'api' categories
}

enum Status #enums {
    // This enum has the 'enums' category
}

// Generate only structs with 'api' category
output typescript @types #api;

Blueprint Language Reference

Blueprints are templates that transform your Repack schemas into target language code.

Template Syntax

Blueprints use bracketed directives: [directive]content[/directive]

Auto-Closing vs Block Directives

Variables

Access schema data through variables:

Core Variables

Variable Modifiers

Transform variable output with dot notation:

Example:

// Input: user_profile
[name.titlecase]     // → User Profile
[name.camelcase]     // → userProfile
[name.uppercase]     // → USER_PROFILE

Control Flow

Iteration

Example:

[each struct]
export interface [name] {
[each field]
    [name]: [type];
[/each]
}
[/each]

Conditionals

Available Flags:

File Generation

File Directives

Import System

// Define import template
[link custom]import type { $ } from './$'[/link]

// Import will be auto-generated when custom types are used
[imports]  // Imports appear here

export interface User {
    profile: UserProfile;  // This triggers the import
}

Type Definitions

Map Repack types to target language types:

[define string]string[/define]
[define int64]number[/define]  
[define boolean]boolean[/define]
[define uuid]string[/define]

Complete Blueprint Examples

TypeScript Interface Generator

[meta id]typescript[/meta]
[meta name]TypeScript Interfaces[/meta]

[define string]string[/define]
[define int64]number[/define]
[define boolean]boolean[/define]
[link custom]import type { $ } from './$'[/link]

[each struct]
[file][name].ts[/file]
[imports]

export interface [name] {
[each field]
    [name][if optional]?[/if]: [type][if array][][\if];
[/each]
}
[/each]

[file]index.ts[/file]
[each struct]
export type { [name] } from './[name]';
[/each]

SQL Schema Generator

[meta id]postgres[/meta]
[meta name]PostgreSQL Schema[/meta]

[define string]TEXT[/define]
[define int64]BIGINT[/define]
[define boolean]BOOLEAN[/define]
[define uuid]UUID[/define]
[define datetime]TIMESTAMPTZ[/define]

[file]schema.sql[/file]
BEGIN;

[each enum]
CREATE TYPE [name] AS ENUM([each case]'[value]'[if sep], [/if][/each]);
[/each]

[each struct]
CREATE TABLE [table_name] (
[each field]
    [name] [type][ifn optional] NOT NULL[/ifn][if sep],[/if]
[/each]
);
[/each]

COMMIT;

Complete Examples

E-commerce System

Schema Definition (ecommerce.repack):

blueprint "typescript.blueprint"
blueprint "postgres.blueprint"

output typescript @src/types;
output postgres @database;

snippet BaseEntity {
    id uuid db:pk
    created_date datetime db:default("NOW()")
    updated_date datetime db:default("NOW()")
}

enum OrderStatus #enums {
    Pending
    Processing  
    Shipped
    Delivered
    Cancelled
}

enum UserRole #enums {
    Customer
    Admin
    Moderator
}

struct User @users #model {
    !BaseEntity
    
    email string db:unique
    first_name string
    last_name string
    role UserRole db:default("'Customer'")
    
    // Computed field
    full_name string db:as("first_name || ' ' || last_name")
    
    query GetByEmail(_email string) = "SELECT $fields FROM $locations WHERE $email = $_email" : one
    query GetAdmins() = "SELECT $fields FROM $locations WHERE $role = 'Admin'" : many
    
    insert CreateUser(id, email, first_name, last_name) : one
    update UpdateName(_id uuid, _first string, _last string) = "SET first_name = $_first, last_name = $_last WHERE $id = $_id" : one
}

struct Product @products #model {
    !BaseEntity
    
    name string
    description string?
    price float64
    inventory_count int32
    is_active boolean db:default("true")
    
    query GetActive() = "SELECT $fields FROM $locations WHERE $is_active = true" : many
    query SearchByName(_name string) = "SELECT $fields FROM $locations WHERE $name ILIKE '%' || $_name || '%'" : many
    
    insert CreateProduct(id, name, price, inventory_count) : one
}

struct Order @orders #model {
    !BaseEntity
    
    user_id uuid
    status OrderStatus db:default("'Pending'")
    total_amount float64
    
    // External field reference
    user_email User.email
    
    query GetByUser(_user_id uuid) = "SELECT $fields FROM $locations WHERE $user_id = $_user_id ORDER BY created_date DESC" : many
    query GetByStatus(_status OrderStatus) = "SELECT $fields FROM $locations WHERE $status = $_status" : many
    
    insert CreateOrder(id, user_id, total_amount) : one
    update UpdateStatus(_id uuid, _status OrderStatus) = "SET $status = $_status WHERE $id = $_id"
}

struct OrderItem @order_items #model {
    !BaseEntity
    
    order_id uuid
    product_id uuid  
    quantity int32
    unit_price float64
    
    // Computed total
    line_total float64 db:as("quantity * unit_price")
    
    query GetByOrder(_order_id uuid) = "SELECT $fields FROM $locations WHERE $order_id = $_order_id" : many
}

// Join example - Orders with user information
struct OrderWithUser : Order {
    join(u User) = "INNER JOIN $name ON $super.user_id = $u.id"
    
    user_name u.full_name
    user_email u.email
    
    query GetOrdersWithUsers() = "SELECT $fields FROM $locations ORDER BY created_date DESC" : many
}

This schema generates:

1. TypeScript interfaces with proper typing
2. PostgreSQL schema with tables, constraints, and indexes
3. Database functions for common operations
4. Type-safe query builders

Blog System

Schema Definition (blog.repack):

snippet Auditable {
    created_date datetime db:default("NOW()")  
    updated_date datetime db:default("NOW()")
    created_by uuid
    updated_by uuid?
}

enum PostStatus {
    Draft
    Published
    Archived
}

struct Author @authors {
    id uuid db:pk
    !Auditable
    
    name string
    email string db:unique
    bio string?
    website string?
    
    query GetByEmail(_email string) = "SELECT $fields FROM $locations WHERE $email = $_email" : one
}

struct Category @categories {
    id uuid db:pk
    !Auditable
    
    name string db:unique
    slug string db:unique
    description string?
    
    query GetBySlug(_slug string) = "SELECT $fields FROM $locations WHERE $slug = $_slug" : one
}

struct Post @posts {
    id uuid db:pk
    !Auditable
    
    title string
    slug string db:unique
    content string
    excerpt string?
    status PostStatus db:default("'Draft'")
    published_date datetime?
    
    author_id uuid
    category_id uuid
    
    // External references
    author_name Author.name
    category_name Category.name
    
    query GetPublished() = "SELECT $fields FROM $locations WHERE $status = 'Published' ORDER BY published_date DESC" : many
    query GetByAuthor(_author_id uuid) = "SELECT $fields FROM $locations WHERE $author_id = $_author_id" : many
    query GetByCategory(_category_id uuid) = "SELECT $fields FROM $locations WHERE $category_id = $_category_id" : many
    
    insert CreatePost(id, title, slug, content, author_id, category_id) : one
    update Publish(_id uuid) = "SET status = 'Published', published_date = NOW() WHERE $id = $_id"
}

struct Tag @tags {
    id uuid db:pk
    name string db:unique
    color string?
}

struct PostTag @post_tags {
    post_id uuid
    tag_id uuid
    
    query GetTagsByPost(_post_id uuid) = "SELECT $fields FROM $locations WHERE $post_id = $_post_id" : many
    query GetPostsByTag(_tag_id uuid) = "SELECT $fields FROM $locations WHERE $tag_id = $_tag_id" : many
}

Best Practices

Blueprint Development

1. Start simple: Begin with basic templates and add complexity gradually
2. Handle edge cases: Use conditionals for optional fields and special cases
3. Maintain consistency: Establish naming conventions in your templates
4. Test thoroughly: Verify generated code with various schema combinations

Project Structure

project/
├── schemas/
│   ├── user.repack
│   ├── product.repack
│   └── order.repack
├── blueprints/
│   ├── typescript.blueprint
│   ├── postgres.blueprint
│   └── docs.blueprint  
├── generated/
│   ├── types/
│   ├── database/
│   └── docs/
└── repack.config

Blueprint Debugging

1. Use debug blueprint: Create simple debug templates to inspect data
2. Check variable scope: Ensure variables are available in current context
3. Validate conditionals: Test flag conditions with debug output
4. Verify imports: Ensure import templates are correctly defined

Happy coding with Repack! 🎉