Documentation
Get started
Define states

Writing your states files

The *.states files are written in Neuledge schema language. The states files are tipically located in the states directory of your project, but you can put them anywhere you want. If you seperate your code into multiple modules, you can keep each module's states on it's own directory.

Adding a new state

To add a new state, you need to create a new file with the .states extension, for example categories.states:

categories.states
"""
This is the category state.
"""
state Category {
  "The category id"
  id: Number = 1
 
  "The category name"
  name: String = 2
}

The state keyword is used to define a new state. The name of the state is Category and it has two fields: id and name. The id field is a Number and the name field is a String. The = 1 and = 2 are the field's indexes. The indexes are used to identify the fields in the state. Both the field names and indexes must be unique within the state.

Adding a primary key

To add a primary key to a state, you need to add the @id decorator to the field definition:

categories.states
state Category {
  "The category id"
  @id(auto: "increment") id: Number = 1
 
  "The category name"
  name: String = 2
}

The @id decorator takes an optional auto argument. The auto argument can be set to "increment" to automatically increment the id when a new state is created. If the auto argument is not set, the id must be set manually when creating a new state.

Optional fields

To make a field optional, you need to add the ? character after the field type:

categories.states
state Category {
  # ...
 
  "The category description"
  description?: String = 3
}

Add additional states

In the example above, we only defined a single state. You can define as many states as you want in a single file. For example, we can create the posts.states file with the following states:

posts.states
state DraftPost {
  @id(auto: "increment") id: Number = 1
  category?: Category = 2
  title: String = 3
  content?: String = 4
}
 
@index(fields: ["category"])
state PublishedPost from DraftPost {
  category: Category = 1
  content: String = 2
  publishedAt: DateTime = 3
}

The PublishedPost state extends the DraftPost state and adds the publishedAt field. It also override the category and content fields to make them required. Neuledge will automatically detect and store both post's states in the same table, and will reuse the same indexes whenever possible.

The @index decorator is used to create an index on the category field. Note that the field category has the same type as the state we defined in the categories.states file. This will automatically creates a foreign key relationship between the category field and the id field of the Category state.

Aliasing multiple states

In order to keep track of all the possible post states, we can create an either type that will alias all the possible post states:

posts.states
either Post = DraftPost | PublishedPost

The either keyword is used to create a new type that can be used to alias multiple states. The Post type can be used to reference any of the DraftPost or PublishedPost states.