Ggtype NPM | npm.io

ggtype

🚀 ggtype is a high-performance TypeScript library designed to make data validation and action management both simple and efficient. Inspired by popular libraries like tRPC and Zod, ggtype offers a streamlined API that is easy to use, yet powerful enough to handle complex business logic.

With ggtype, you can:

Validate Data: Ensure that your data is correctly structured and adheres to your defined types, giving you confidence in the integrity of your data across your application.
Manage Actions: Define and execute actions that operate on your data models, whether they are simple operations or part of a more complex workflow.
Create Type-Safe APIs: Just like tRPC, ggtype allows you to build type-safe APIs without needing to write a lot of boilerplate code.
Handle Complex Logic: Use ggtype to combine multiple actions into a workflow, managing dependencies and execution order effortlessly.

Note: This library is still in beta. Feedback and contributions are welcome! Also there are missing client and server libraries, this is more like core library.

Key Features

Define Data Models: Easily create models to define the structure of your data.
Type Inference: Automatically generate TypeScript types from your models, so you don't have to manually write them.
Manage Actions: Create actions that work with your data models, supporting both simple and complex tasks.
Combine Actions: Group multiple actions together and run them in a specific order.
Handle Errors: Built-in error handling for predictable and clear error management.

Installation

You can install ggtype using Bun, Yarn, or npm:

Using Bun:

bun add ggtype

Using Yarn or npm:

yarn add ggtype  # or npm i ggtype

Quick Start Guide

Here's a simple example to help you get started:

Define a Model and Action

Create a Data Model: Define what your data should look like.

import { m } from 'ggtype'

const userModel = m.object({
  id: m.string().isRequired(),
  name: m.string(),
})

Create an Action: Set up an action that uses this model.

import { action } from 'ggtype'

const createUserAction = action(userModel, async ({ params }) => {
  return {
    isJohnDoe: params.name === 'John Doe',
  }
})

Combine Actions into a Graph: Group your actions together for more complex workflows.

import { graph } from 'ggtype'

const app = graph({
  createUser: createUserAction,
})

const result = await app.parse({
  createUser: { id: '1', name: 'John Doe' },
})

console.log(result.createUser.ok?.isJohnDoe) // Output: true

Full Example

Here's how to define a model, compile it for validation, and use it in actions:

import { compileModel, m, action, graph, type Infer } from 'ggtype'

// Define your data model
const userModel = m.object({
  id: m.string().isRequired(),
  name: m.string(),
  profile: m.object({
    age: m.number().isRequired(),
  }),
  friends: m.array(m.object({
    user_id: m.string().isRequired(),
  })),
})

// Compile the model for validation
const compiledModel = compileModel(userModel)

// Use the model in an action
const createUserAction = action(userModel, ({ params }) => {
  return params.name
})

// Combine actions in a graph
const app = graph({
  createUser: createUserAction,
})

// Run the graph with some data
const result = await app.parse({
  createUser: {
    id: '1',
    name: 'John Doe',
    profile: { age: 30 },
    friends: [{ user_id: '2' }],
  },
})

console.log(result.createUser.ok) // Output: John Doe

Performance Note

The validation part of ggtype uses AJV, which is significantly faster than other libraries like Zod. Benchmarks for tRPC don't exist yet, but ggtype is designed to be more performant while being just as easy to use.

API Overview

m.object: Define a structured data model.
action: Create actions that work with your models.
graph: Group actions into workflows.
ValidationError: Handle validation errors easily.

Testing

Testing with ggtype is straightforward. Here’s a simple example:

import { object, string, action } from 'ggtype'

describe('action', () => {
  it('should fail with invalid params', () => {
    const userModel = object({
      id: string().isRequired(),
      createdAt: string(),
    })

    const someAction = action(userModel, ({ params }) => {
      return params.createdAt
    })

    expect(() => {
      someAction.fn({
        context: {},
        params: {} as unknown as { id: string },
      })
    }).toThrow(ValidationError)
  })
})

Contributing

We welcome contributions! If you find a bug or have a suggestion, please open an issue. To contribute code, fork the repository and submit a pull request.