KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

haykal

★ 23 Open GitHub ↗

A Typescript MVC Framework

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Haykal
---
# Deprecated
version 0.1.* has been deprecated due to both architectural and tooling reasons, here's a list of the current issues:

##### Architecture
- The non-standard MVC terminology confuses newcomers
- The MVC structure did not scale well, business logic in the controller made it hard to reuse code between other controllers
- Repositories did not support transactions out of the box, hacking them in was not convenient
- A lot of repeated code, between interfaces, repositories and repository interfaces
- Having models be interfaces and only define domain method types made for a lot of code repetition
- Having both an implementation and interface for repositories proved to have little value, as long as the implementation repository did not leak the DB layer
- Lack of colocation made making changes to one component have you jumping between routes, controllers, model interfaces, repository interfaces, and the repository implementations, each in its own directory
- manual DI did not scale well, files got larger, introducing new repositories meant more imports and editing of controller initialization.

##### Tooling
The CLI code is badly structured, and the template strings have no typesafety and the generated code had bad formatting.

### Moving forward
version 0.2 is in development, I've been experimenting with multiple new structures, and after 4 drafts and a few months of use in development, I think I've picked
a lay out for 0.2 that I believe addresses all the pain points mentioned earlier, inspired by DDD in decoupling the domain models, unit of work for decoupled transactions, and angular in colocation of files, and making use of tsyringe for handling DI, among other improvements.

Work will also be put into making the CLI project structure cleaner, and I'll be experimenting with using ts-morph for code generation.

And documentation, this has been severly lacking 😓

---
Haykal is a typescript MVC framework, originally designed for generating web application backends, it is flexible enough to work with any project. Haykal generates a loosely coupled project, and is able to generate component templates.

Haykal uses Express and Objection/Knex by default, but it's decoupled and can be replaced by other
equivalent libraries and frameworks. Support for other libraries will come after.

### How to use
haykal is a cli tool, install it through

`npm i -g haykal`
current available commands are:

- initialize a new project:
    `haykal init <project-name>`
    creates a new folder in the current
    directory, installs dependencies and generates the folders and files and creates the project boilerplate

- generate components:
    `haykal gen [options] <component>`
    type of resource can chosen through these options:
       - -a: resource  // generates all components with CRUD methods for the controller and routes
       - -c: controller
       - -r: router
       - -i: model interface
       - -m: model implementation
       - -mi: migration
       
    and optionally attributes options `--attributes` (e.g : `--attributes id:primary name:string age:number`)
    currently supported types: `string`, `number`, `date`, `boolean` and `primary` (incremental id)
    if you do not enter the attributes option you're able to add them after running the command.
    if you're generating a component without attributes (e.g a router or controller), just hit enter after the command.

### Project Structure:

```
 /src
    - /controllers
        - <controller classes>
    - /dependency
        - index.ts
        - config.ts
    - /models
        - /interface
            - base.ts
            - <model interfaces>
        - /<implementation> (e.g objection)
            - base.ts
            - <model implementation classes>
    - /tests
        - <test files>
    - /services
        - <service classes>
    - /application
        - /<implementation> (e.g express)
            - index.ts
            - error.ts
            - /api
                - /v1
                    - index.ts
                    - <routes>
                - index.ts
    - /db
        - /<implementation> (e.g objection)
            - index.ts
    - /exceptions
        - index.ts
- Controllers:
    Unlike other MVC frameworks, controllers are not the HTTP route handlers, those are inside route files.
    Controllers are the logic side of Models in the usual MVC pattern, and they handle only business rules.
- Models:
    In practice, repositories, they define a standard way to interface with your chosen data store.
    interfaces hold the standard method definitions, while implementation folders contain the ORM/SQL/HttpRequests required to fulfill the implementation.
    - interface:
        defines a common interface to be implemented by model repositories.
    - implementation:
        the repository implementation classes, if using an ORM, defines the ORM Model here and a repository class that implements the interface methods using said ORM.
- Dependency:
    - index.ts:
        initializes dependency injection and exports instances of classes and models.
    - config.ts:
        defines a central place to read environment variable and define default values for them.
- Tests:
    includes all test files.
- Application:
    handles all application's access implementations, could be a HTTP server, a CLI tool, etc the following example is of the Express implementation.
    - express:
        - index.ts:
            bootstraps the entire application.
        - error.ts:
            generic express error handler.
        - api:
            index.ts:
                handles registering all api routes, reads every folder and imports it as router for use(e.g "/v1").
            v1:
                the default api version.
                - index.ts:
                    handles registering all routers within its directory.
- DB:
    defines DB access configuration files.
    - databaseImplementation:
        the config for the chosen implementation.
- Exceptions:
    - index.ts:
        Holds exception and error classes.
```

haykal

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README