Entity
An Entity is a class that describes one kind of business record, such as an order or a customer. You reach it as This.<EntityName>: use it as a type, create instances with new, and read and write their properties.
Availability: Everywhere
How to reach it
Section titled “How to reach it”| Access path | What it is |
|---|---|
This.<EntityName> | The Entity class: its constructor, static members and the type of its instances. |
This.<EntityName>.<SubsetName> | A subset class of the Entity. |
This.<EntityName>.Id | The Entity’s id type, and the matching constructor as a value. |
Entities are not grouped under a $ namespace.
Note
Entities have no save, load or delete methods. Lowgile stores and loads Entities only through the static methods of a Server Data Store, for example This.MyDataStore.saveOne(order).
Functions
Section titled “Functions”constructor()
Section titled “constructor()”constructor(init?: Partial<<EntityName>>, initOneToManyRelations?: boolean)Creates an instance of the Entity and copies the values of init into it.
| Parameter | Type | Description |
|---|---|---|
init | Partial<<EntityName>> | Optional. Property values for the new instance. |
initOneToManyRelations | boolean | Optional. If true, every one-to-many relation that init does not set starts as an empty array. Default: false. |
If the Entity defines its own method named constructor, the class uses that method’s signature instead. Subset classes always use the signature above.
Returns: a new <EntityName> · Availability: Everywhere
$clone()
Section titled “$clone()”$clone(): <EntityName>Returns a deep copy of the instance: related objects and arrays are copied too, and an object referenced twice is copied once.
Returns: <EntityName> · Availability: Everywhere
$updateFrom()
Section titled “$updateFrom()”$updateFrom(source: Partial<<EntityName>>): voidCopies the values of every property of source that the instance also has. Values are assigned as they are, so related objects are shared rather than copied.
| Parameter | Type | Description |
|---|---|---|
source | Partial<<EntityName>> | The object to copy values from. |
Returns: void · Availability: Everywhere
Properties
Section titled “Properties”id: <EntityName>.IdThe record’s id. Lowgile fills it in when a Server Data Store saves a new record. Entities whose id type is none have no id.
Type: <EntityName>.Id · Availability: Everywhere
<propertyName>
Section titled “<propertyName>”<propertyName>: <type>One property per Entity property, typed as defined in the Entity. Properties defined as static are static members of the class (This.<EntityName>.<propertyName>). A subset class has only the properties included in the subset.
Type: the property’s type · Availability: Everywhere
<propertyName>$id
Section titled “<propertyName>$id”'<propertyName>$id': string | numberFor each property whose type is a Static Entity, holds the id of the selected entry. Setting it selects a different entry. The property name contains $, so read it with brackets: order['status$id'].
Type: the Static Entity’s id type, string or number · Availability: Everywhere
<SubsetName>
Section titled “<SubsetName>”static <SubsetName>: typeof <EntityName>.<SubsetName>The subset class, as a static member of the Entity class. Server Data Store methods accept a subset class wherever they accept the Entity class.
Type: typeof <EntityName>.<SubsetName> · Availability: Everywhere
<EntityName>.Id
Section titled “<EntityName>.Id”type Id = NominalType<string | number, '<ModuleId>.<EntityName>'>const Id: typeof String | typeof NumberThe id type of the Entity: string or number, marked with the Entity’s qualified name so that TypeScript does not accept the id of one Entity where another Entity’s id is expected. As a value, This.<EntityName>.Id is the String or Number constructor. It does not exist for Entities whose id type is none.
Availability: Everywhere
<EntityName>.<SubsetName>
Section titled “<EntityName>.<SubsetName>”class <SubsetName> { … }A class with the Entity’s id, the properties and methods included in the subset, and the same constructor(), $clone() and $updateFrom() as the Entity.
Availability: Everywhere
Methods you define
Section titled “Methods you define”The methods you add to an Entity are members of its class. Each method’s availability setting decides in which code it is declared and how it runs:
| Setting | Server-side code | Client-side code | Shared code (serverAndClient) | Calculation code |
|---|---|---|---|---|
serverOnly | Available | Not available | Not available | Not available |
clientOnly | Not available | Available | Not available | Not available |
serverAndClient | Available | Available | Available | Available only if the method is not async |
calculation | Available as a getter | Available as a getter | Available as a getter | Available as a getter |
callableFromClient | Available, with an extra first parameter clientThis | Available as a call to the server, with an extra first parameter serverStore | Declared, but don’t call it from here (see below) | Not available |
“Not available” means the method is not part of the class’s type in that code, so calling it is a type error.
calculation methods
Section titled “calculation methods”A calculation method becomes a read-only property: Lowgile declares and generates it as get <methodName>(): <returnType>. Read it without parentheses, for example order.totalAmount.
Availability: Everywhere
callableFromClient methods
Section titled “callableFromClient methods”A callableFromClient method runs on the server, but client-side code can call it. Instance methods get one extra first parameter, which differs per side:
// client-side<methodName>(serverStore: typeof This.<ServerDataStoreName> | null, ...inputs): Promise<<returnType>>// server-side<methodName>(clientThis: <EntityName>, ...inputs): <returnType>| Parameter | Side | Description |
|---|---|---|
serverStore | Client | A Server Data Store of the Module that stores this Entity, or null. The server uses it to load the stored version of the instance. |
clientThis | Server | The instance as the client sent it, with the values it had on the client. |
On the client the method is always async and returns a Promise, even if its return type is not one. Lowgile sends the instance and the remaining arguments to the server and returns the server’s result. Static methods get no extra parameter. The method’s access mode decides who may call it: everyone, any logged-in End user, or as granted by Access Control.
Availability: Both¹
Note
When the call comes from the client, this inside the method on the server is the version loaded from the database through serverStore, but only if an Access Control rule loaded it while checking access. Otherwise this is undefined. Read the client’s values from clientThis.
Note
In shared code (serverAndClient), a callableFromClient instance method is declared returning a Promise but without the extra first parameter. Both runtimes expect that parameter, so the call passes your first argument in its place. Call these methods from server-side or client-side code only.
Related
Section titled “Related”- Server Data Store API
- Static Entity API
- Transactional Entities
- Access Control
¹ On the client, the call is sent to the server and is subject to access control.