@selfage/generator_cli

Turn a single YAML description into TypeScript code for data models, HTTP APIs, and Cloud Spanner schema.

Why use this CLI?

• Describe enums, messages, service APIs, and database schema once and generate the boilerplate automatically.
• Keep TypeScript types and runtime descriptors in sync without hand-editing multiple files.
• Preview output with --dry-run, or run the generator in CI/CD with npx geneage.
• Plays nicely with the @selfage/* runtime packages so the emitted code is executable right away.

Installation

npm install --save-dev @selfage/generator_cli

The binary is published as geneage. Invoke it with npx or wire it into a package.json script.

Quick start

1. Write your definitions in YAML (the file must use the .yaml extension):

   - kind: Enum
     name: UserRole
     values:
       - { name: ADMIN, value: 1 }
       - { name: VIEWER, value: 2 }
   
   - kind: Message
     name: User
     fields:
       - { name: id, type: string, index: 1 }
       - { name: role, type: UserRole, index: 2 }
   
   - kind: Message
     name: GetUserRequest
     fields:
       - { name: id, type: string, index: 1 }
   
   - kind: Service
     name: UserService
     path: /user.v1.UserService
   
   - kind: RemoteCallsGroup
     name: UserClient
     service: UserService
     outputClient: ./generated/user_client
     outputHandler: ./generated/user_handlers
     calls:
       - name: GetUser
         path: /users/get
         body: GetUserRequest
         response: User
   
   - kind: SpannerDatabase
     name: UserDb
     outputDdl: ./generated/user_db_schema
     outputSql: ./generated/user_queries
     tables:
       - kind: Table
         name: UserTable
         columns:
           - { name: id, type: string }
           - { name: role, type: string }
         primaryKeys: [ id ]

2. Run the generator from the directory that contains the definition file:

   npx geneage ./definition.yaml

3. Review the emitted .ts and .json files in the target paths. Use --dry-run to print the generated content without touching the filesystem.

What gets generated?

• Enum – TypeScript enums with an accompanying descriptor for @selfage/message.
• Message – TypeScript interfaces with an accompanying descriptor for @selfage/message.
• Service API – service API handler and client interfaces to be used together with @selfage/serivce_handler, @selfage/web_service_client, and @selfage/node_service_client.
• Spanner Database – Cloud Spanner DDL JSON and strongly typed query helpers to be used with @google-cloud/spanner.

CLI reference

geneage [options] <definitionFile>

Options:

• -V, --version – show the CLI version.
• --dry-run – write the generated content to stdout instead of to disk.
• -h, --help – display the usage guide.

The tool resolves <definitionFile> to <definitionFile>.yaml, so you can omit the .yaml suffix when convenient.

Examples

The test_data/generator/ directory contains end-to-end samples that cover every definition type. Use them as a reference when crafting your own YAML files.