@udraft/cursor/README.md

uDraft Cursor enables you to declarative write code generators!

# uDraft Cursor (@udraft/cursor)

uDraft Cursor is a library that enables developers to create code generators for any language in a declarative and flexible way.

## Installation

To install the library, use npm or yarn:

```sh
npm install @udraft/cursor
# or
yarn add @udraft/cursor
```

## Introduction

With uDraft Cursor, you can define data structures and dynamically generate code from them. The library allows you to manipulate and structure output with a declarative flow, simplifying the creation of custom code generators.

## Usage Example

The example below demonstrates how to use uDraft Cursor to dynamically generate a TypeScript class:

### Defining the Data Structure

```typescript
import { uCursor } from "@udraft/cursor";

export interface Root {
  className: string;
  extends?: string;
  props: Prop[];
  methods: Method[];
  info?: {
    version: string;
  };
}

export interface Prop {
  name: string;
  type?: string;
}

export interface Method {
  name: string;
  type: string;
  params: Param[];
}

export interface Param {
  name: string;
  type: string;
}

const data: Root = {
  className: "Person",
  extends: "Human",
  info: {
    version: "1.0.0",
  },
  props: [
    { name: "name", type: "string" },
    { name: "age", type: "string" },
    { name: "gender", type: "Gender" },
  ],
  methods: [
    {
      name: "fromJson",
      type: "Person",
      params: [{ name: "json", type: "any" }],
    },
    {
      name: "concat",
      type: "string",
      params: [
        { name: "a", type: "string" },
        { name: "b", type: "string" },
      ],
    },
  ],
};
```

### Generating the Code

```typescript
const cursor = uCursor<Root>()
  .prefix("export class ")
  .block(" {", "}")
  .ident({ char: " ", size: 2 })
  .writeFrom("className", (name) => name)
  .writeFrom("extends", (name) => (name ? ` extends ${name}` : ""))
  .in("info", (info) =>
    info.writeFrom("version", (version) => `// Version: ${version}\n\n`)
  )
  .each("props", (prop) =>
    prop
      .write(({ name, type }) => `${name}: ${type};`)
      .join("\n")
      .clean()
  )
  .linebreak(2)
  .each("methods", (method) =>
    method
      .writeFrom("name", (name) => name + "(")
      .writeFromEach(
        "params",
        ({ name, type }, _, { isLast }) =>
          `${name}: ${type}${!isLast ? ", " : ""}`
      )
      .write(() => ")")
      .writeFrom("type", (type) => ": " + type)
      .block(" {", "}")
      .join("\n\n")
  )
  .clean();

console.log(cursor.render(data));
```

### Generated Output

```typescript
export class Person extends Human {
  // Version: 1.0.0

  name: string;
  age: string;
  gender: Gender;

  fromJson(json: any): Person {}

  concat(a: string, b: string): string {}
}
```

## Key Features

- **Declarative Approach**: Define how the code should be generated rather than manually handling string manipulation.
- **Data Structure Support**: Uses input objects to structure the output.
- **Flexible Transformations**: Allows dynamic modification and formatting of generated code.
- **Blocks and Indentation**: Helps create well-organized code structures.