Skip to content

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

Access pathWhat 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>.IdThe 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).

constructor(init?: Partial<<EntityName>>, initOneToManyRelations?: boolean)

Creates an instance of the Entity and copies the values of init into it.

ParameterTypeDescription
initPartial<<EntityName>>Optional. Property values for the new instance.
initOneToManyRelationsbooleanOptional. 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(): <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(source: Partial<<EntityName>>): void

Copies 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.

ParameterTypeDescription
sourcePartial<<EntityName>>The object to copy values from.

Returns: void · Availability: Everywhere

id: <EntityName>.Id

The 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>: <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': string | number

For 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

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

type Id = NominalType<string | number, '<ModuleId>.<EntityName>'>
const Id: typeof String | typeof Number

The 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

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

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:

SettingServer-side codeClient-side codeShared code (serverAndClient)Calculation code
serverOnlyAvailableNot availableNot availableNot available
clientOnlyNot availableAvailableNot availableNot available
serverAndClientAvailableAvailableAvailableAvailable only if the method is not async
calculationAvailable as a getterAvailable as a getterAvailable as a getterAvailable as a getter
callableFromClientAvailable, with an extra first parameter clientThisAvailable as a call to the server, with an extra first parameter serverStoreDeclared, 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.

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

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>
ParameterSideDescription
serverStoreClientA Server Data Store of the Module that stores this Entity, or null. The server uses it to load the stored version of the instance.
clientThisServerThe 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.

¹ On the client, the call is sent to the server and is subject to access control.