Repository

@webda/models

---

Interface: Repository<T>

Defined in: packages/models/src/repositories/repository.ts:453

Full-featured repository combining all capabilities (backward compatible)

This is the main interface that most code will interact with. It extends all specialized interfaces for backward compatibility.

Note: All methods are inherited from:

• CoreRepository: Basic CRUD, query, and key management
• Updatable: Update, patch, and upsert operations
• AtomicOperations: Atomic increment, setAttribute, removeAttribute
• CollectionOperations: Array/collection manipulation

Extends

• CoreRepository<T>
• Updatable<T>
• AtomicOperations<T>
• CollectionOperations<T>

Type Parameters

T

T extends ModelClass = ModelClass

Properties

[WEBDA_TEST]?

optional [WEBDA_TEST]?: object

Defined in: packages/models/src/repositories/repository.ts:258

clear()

clear(): Promise<void>

Returns

Promise<void>

Inherited from

CoreRepository.[WEBDA_TEST]

Methods

aggregate()

aggregate<G, M>(spec, params?): Promise<AggregationResult<AggregatedRow<InstanceType<T>, G, M>>>

Defined in: packages/models/src/repositories/repository.ts:162

Aggregate the store

repo.aggregate({ filter: "done = FALSE", groupBy: ["status"], metrics: { n: { count: "*" } } });

Type Parameters

G

G extends readonly _NonFunctionPropertyPaths<InstanceType<T>>[] = []

M

M extends Record<string, MetricSpec<InstanceType<T>>> = Record<string, MetricSpec<InstanceType<T>>>

Parameters

spec

AggregationSpec<InstanceType<T>, G, M>

filter, group by paths, metrics, ordering and limit

params?

QueryParameters

values for the placeholders of spec.filter

Returns

Promise<AggregationResult<AggregatedRow<InstanceType<T>, G, M>>>

the aggregated rows and whether the backend computed them natively

Inherited from

CoreRepository.aggregate

---

configureAggregation()

configureAggregation(options): void

Defined in: packages/models/src/repositories/repository.ts:195

Configure the aggregation fallback policy, called by the owning store

Parameters

options

Partial<AggregationOptions>

options to override

Returns

void

Inherited from

CoreRepository.configureAggregation

---

configureMonitoring()?

optional configureMonitoring(options): void

Defined in: packages/models/src/repositories/repository.ts:201

Configure the query monitoring policy, called by the owning store

Parameters

options

Partial<QueryMonitorOptions>

options to override

Returns

void

Inherited from

CoreRepository.configureMonitoring

---

count()

count(filter?, params?, options?): Promise<CountResult>

Defined in: packages/models/src/repositories/repository.ts:185

Count the objects matching a filter

repo.count("status = 'open'", undefined, { max: 10000 }); // { value: 1234, relation: "eq", native: true }

ORDER BY, LIMIT and OFFSET of the filter are ignored; DELETE, UPDATE and SELECT field lists are refused. Backends without a native count scan the matching objects in memory, under the aggregation fallback policy. Counts bypass the model permissions: see countModelWithPermissions in @webda/core for a client total.

Parameters

filter?

WebdaQLString<InstanceType<T>>

the WebdaQL filter, optionally with ? or :name placeholders; empty counts everything

params?

QueryParameters

values for the placeholders: an array for ?, an object for :name

options?

CountOptions

max stops counting after max objects (relation "gte")

Returns

Promise<CountResult>

the count, whether it is exact and whether the backend computed it natively

Throws

AggregationError AGGREGATION_NOT_NATIVE when the backend has no native count and the policy is deny

Inherited from

CoreRepository.count

---

create()

create(data, save?): Promise<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:102

Create data in the store

Parameters

data

Helpers<InstanceType<T>>

save?

boolean

if false, create in-memory object without saving

Returns

Promise<InstanceType<T>>

Inherited from

CoreRepository.create

---

delete()

delete<K>(uid, conditionField?, condition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:111

Delete data from the store

Type Parameters

K

K extends string

Parameters

uid

string | PrimaryKeyType<InstanceType<T>>

Primary key or UID string

conditionField?

K | null

Field to check for condition (optional)

condition?

_PropertyPathType<InstanceType<T>, K> | JSONed<_PropertyPathType<InstanceType<T>, K>>

Value to check for condition (optional)

Returns

Promise<void>

Inherited from

CoreRepository.delete

---

deleteItemFromCollection()

deleteItemFromCollection<K, L>(primaryKeyOrUid, collection, index, itemWriteConditionField?, itemWriteCondition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:407

Remove item from a collection by index

Type Parameters

K

K extends string

L

L extends string | number | symbol

Parameters

primaryKeyOrUid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object containing the collection

collection

K

Name of the array field

index

number

Position of item to remove

itemWriteConditionField?

L

Field to check for condition on item

itemWriteCondition?

ArrayElement<InstanceType<T>[K]>[L]

Expected value for condition field on item

Returns

Promise<void>

Inherited from

CollectionOperations.deleteItemFromCollection

---

deleteMany()

deleteMany(statement, params?): Promise<number>

Defined in: packages/models/src/repositories/repository.ts:218

Delete every object matching a DELETE [WHERE ...] [LIMIT n] statement, in bulk

Bulk operations bypass the model layer: no per-object repository event (Delete/Deleted), no model hook, no behaviour and no validation run, and no permission (canAct) is checked. Repositories are trusted internal APIs: application code exposing a bulk statement to clients must check permissions itself.

Stores use their native batch operation when they have one, otherwise the matching keys are collected first (up to LIMIT) and deleted with the store's per-key primitive.

Parameters

statement

Query | WebdaQLStatement<InstanceType<T>>

the DELETE statement, optionally with ? or :name placeholders, or its parsed form

params?

QueryParameters

values for the placeholders: an array for ?, an object for :name

Returns

Promise<number>

the number of objects deleted

Throws

if the statement is not a DELETE

Inherited from

CoreRepository.deleteMany

---

emit()

emit<K>(event, payload): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:253

Type Parameters

K

K extends string | number | symbol

Parameters

event

K

payload

InstanceType<T>[typeof WEBDA_EVENTS][K]

Returns

Promise<void>

Inherited from

CoreRepository.emit

---

excludePrimaryKey()

excludePrimaryKey(object): any

Defined in: packages/models/src/repositories/repository.ts:81

Remove the primary key from the object

Parameters

object

any

Returns

any

Inherited from

CoreRepository.excludePrimaryKey

---

exists()

exists(uid): Promise<boolean>

Defined in: packages/models/src/repositories/repository.ts:122

Verify if the object exists

Parameters

uid

string | PrimaryKeyType<InstanceType<T>>

Returns

Promise<boolean>

Inherited from

CoreRepository.exists

---

fromUID()

fromUID(uid, forceObject?): ModelRefWithCreate<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:52

In REST API, composite keys are represented as a string with the format "key1#key2#key3" We need a way to convert this string to the object

Parameters

uid

string

serialized primary key

forceObject?

boolean

if true, the result will be an object with the primary key fields

Returns

ModelRefWithCreate<InstanceType<T>>

Inherited from

CoreRepository.fromUID

---

get()

get(primaryKey): Promise<HelperProperties<InstanceType<T>>>

Defined in: packages/models/src/repositories/repository.ts:94

Get data from the store

Parameters

primaryKey

PrimaryKeyType<InstanceType<T>>

Returns

Promise<HelperProperties<InstanceType<T>>>

Inherited from

CoreRepository.get

---

getPrimaryKey()

getPrimaryKey<K>(object, forceObject?): K extends false ? PrimaryKeyType<InstanceType<T>> : PrimaryKey<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:66

Extract the primary key from the object

Type Parameters

K

K

Parameters

object

any

to extract the primary key from

forceObject?

boolean

if true, the result will be an object with the primary key fields

Returns

K extends false ? PrimaryKeyType<InstanceType<T>> : PrimaryKey<InstanceType<T>>

Inherited from

CoreRepository.getPrimaryKey

---

getRootModel()

getRootModel(): T

Defined in: packages/models/src/repositories/repository.ts:43

Get the root model class for this repository

Returns

T

Inherited from

CoreRepository.getRootModel

---

getUID()

getUID(object): string

Defined in: packages/models/src/repositories/repository.ts:75

Get the UID of the object

Parameters

object

any

to extract the primary key from

Returns

string

Inherited from

CoreRepository.getUID

---

incrementAttribute()

incrementAttribute<K, L>(primaryKeyOrUid, info, conditionField?, condition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:331

Atomically increment a single numeric field

Type Parameters

K

K extends string

L

L extends string

Parameters

primaryKeyOrUid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object to update

info

L | { property: L; value?: number; }

Field to increment with optional value (default: 1)

conditionField?

K | null

Field to check for condition

condition?

_PropertyPathType<InstanceType<T>, K> | JSONed<_PropertyPathType<InstanceType<T>, K>>

Expected value for condition field

Returns

Promise<void>

Inherited from

AtomicOperations.incrementAttribute

---

incrementAttributes()

incrementAttributes<K, L>(primaryKeyOrUid, info, conditionField?, condition?): Promise<void | Record<string, number>>

Defined in: packages/models/src/repositories/repository.ts:317

Atomically increment numeric field(s)

Type Parameters

K

K extends string

L

L extends string

Parameters

primaryKeyOrUid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object to update

info

(L | { property: L; value?: number; })[] | Record<L, number>

Fields to increment with optional values (default: 1)

conditionField?

K | null

Field to check for condition

condition?

_PropertyPathType<InstanceType<T>, K> | JSONed<_PropertyPathType<InstanceType<T>, K>>

Expected value for condition field

Returns

Promise<void | Record<string, number>>

Inherited from

AtomicOperations.incrementAttributes

---

iterate()

iterate(query, params?): AsyncGenerator<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:150

Iterate over the store

Takes a filter query (a = 1 ORDER BY b LIMIT 10): DELETE and UPDATE statements go to deleteMany / updateMany, and SELECT field lists are refused (objects are returned whole).

Parameters

query

WebdaQLString<InstanceType<T>>

the WebdaQL query, optionally with ? or :name placeholders

params?

QueryParameters

values for the placeholders: an array for ?, an object for :name

Returns

AsyncGenerator<InstanceType<T>>

Inherited from

CoreRepository.iterate

---

off()

off<K>(event, listener): void

Defined in: packages/models/src/repositories/repository.ts:249

Type Parameters

K

K extends string | number | symbol

Parameters

event

K

listener

(data) => void

Returns

void

Inherited from

CoreRepository.off

---

on()

on<K>(event, listener): void

Defined in: packages/models/src/repositories/repository.ts:241

Event listeners

Type Parameters

K

K extends string | number | symbol

Parameters

event

K

listener

(data) => void

Returns

void

Inherited from

CoreRepository.on

---

once()

once<K>(event, listener): void

Defined in: packages/models/src/repositories/repository.ts:245

Type Parameters

K

K extends string | number | symbol

Parameters

event

K

listener

(data) => void

Returns

void

Inherited from

CoreRepository.once

---

parseUID()

parseUID(uid, forceObject?): PrimaryKeyType<InstanceType<T>> | PrimaryKey<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:59

Parse the UID into the primary key

Parameters

uid

string

forceObject?

boolean

Returns

PrimaryKeyType<InstanceType<T>> | PrimaryKey<InstanceType<T>>

Inherited from

CoreRepository.parseUID

---

patch()

patch<K>(uid, data, conditionField?, condition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:288

Partially update object (only specified fields)

Type Parameters

K

K extends string

Parameters

uid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object to update

data

Partial<Omit<InstanceType<T>, PrimaryKeyAttributes<InstanceType<T>>>>

Partial object data (only fields to update)

conditionField?

K | null

Field to check for optimistic locking (null = no check)

condition?

_PropertyPathType<InstanceType<T>, K> | JSONed<_PropertyPathType<InstanceType<T>, K>>

Expected value for condition field

Returns

Promise<void>

Inherited from

Updatable.patch

---

query()

query(query, params?): Promise<{ continuationToken?: string; results: InstanceType<T>[]; }>

Defined in: packages/models/src/repositories/repository.ts:133

Query the store

Takes a filter query (a = 1 ORDER BY b LIMIT 10): DELETE and UPDATE statements go to deleteMany / updateMany, and SELECT field lists are refused (objects are returned whole).

Parameters

query

WebdaQLString<InstanceType<T>>

the WebdaQL query, optionally with ? or :name placeholders

params?

QueryParameters

values for the placeholders: an array for ?, an object for :name

Returns

Promise<{ continuationToken?: string; results: InstanceType<T>[]; }>

Inherited from

CoreRepository.query

---

ref()

ref(pk): ModelRefWithCreate<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:87

Refers to the object in the store

Parameters

pk

SettablePrimaryKey<InstanceType<T>>

primary key

Returns

ModelRefWithCreate<InstanceType<T>>

Inherited from

CoreRepository.ref

---

removeAttribute()

removeAttribute<L, K>(primaryKeyOrUid, attribute, conditionField?, condition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:361

Atomically remove an attribute

Type Parameters

L

L extends string

K

K extends string

Parameters

primaryKeyOrUid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object to update

attribute

K

Attribute name to remove

conditionField?

L | null

Field to check for condition

condition?

_PropertyPathType<InstanceType<T>, L> | JSONed<_PropertyPathType<InstanceType<T>, L>>

Expected value for condition field

Returns

Promise<void>

Inherited from

AtomicOperations.removeAttribute

---

setAttribute()

setAttribute<K, L>(primaryKeyOrUid, attribute, value, conditionField?, condition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:346

Atomically set a single attribute value

Type Parameters

K

K extends string

L

L extends string

Parameters

primaryKeyOrUid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object to update

attribute

K

Attribute name to set

value

_PropertyPathType<InstanceType<T>, K>

New value for attribute

conditionField?

L | null

Field to check for condition

condition?

_PropertyPathType<InstanceType<T>, L> | JSONed<_PropertyPathType<InstanceType<T>, L>>

Expected value for condition field

Returns

Promise<void>

Inherited from

AtomicOperations.setAttribute

---

update()

update<K>(data, conditionField?, condition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:275

Replace entire object (full update)

Type Parameters

K

K extends string

Parameters

data

Helpers<InstanceType<T>>

Complete object data including primary key

conditionField?

K | null

Field to check for optimistic locking (null = no check)

condition?

_PropertyPathType<InstanceType<T>, K>

Expected value for condition field

Returns

Promise<void>

Inherited from

Updatable.update

---

updateMany()

updateMany(statement, params?): Promise<number>

Defined in: packages/models/src/repositories/repository.ts:236

Update every object matching an UPDATE SET a = v, ... [WHERE ...] [LIMIT n] statement, in bulk

Bulk operations bypass the model layer: no per-object repository event (Patch/Patched/Updated), no model hook, no behaviour and no validation run, and no permission (canAct) is checked. Repositories are trusted internal APIs: application code exposing a bulk statement to clients must check permissions itself.

SET targets may not be a primary key field nor a private (__) field, and must be fields of the model when its metadata lists them. Dotted targets (profile.verified) set a nested value, creating the intermediate objects. Each matching object is updated once, even when the SET changes a field of the WHERE.

Parameters

statement

Query | WebdaQLStatement<InstanceType<T>>

the UPDATE statement, optionally with ? or :name placeholders, or its parsed form

params?

QueryParameters

values for the placeholders: an array for ?, an object for :name

Returns

Promise<number>

the number of objects updated

Throws

if the statement is not an UPDATE, or a SET target is refused

Inherited from

CoreRepository.updateMany

---

upsert()

upsert(data): Promise<InstanceType<T>>

Defined in: packages/models/src/repositories/repository.ts:298

Create or update object (insert if not exists, update if exists)

Parameters

data

Helpers<InstanceType<T>>

Returns

Promise<InstanceType<T>>

Inherited from

Updatable.upsert

---

upsertItemToCollection()

upsertItemToCollection<K, L>(primaryKeyOrUid, collection, item, index?, itemWriteConditionField?, itemWriteCondition?): Promise<void>

Defined in: packages/models/src/repositories/repository.ts:385

Add or update item in a collection (array field)

Type Parameters

K

K extends string

L

L extends string | number | symbol

Parameters

primaryKeyOrUid

string | PrimaryKeyType<InstanceType<T>>

Primary key of object containing the collection

collection

K

Name of the array field

item

ArrayElement<InstanceType<T>[K]> | JSONed<ArrayElement<InstanceType<T>[K]>>

Item to add/update

index?

number

Position to insert (undefined = append to end)

itemWriteConditionField?

ArrayElement<InstanceType<T>[K]> extends object ? L : never

Field to check for condition on item

itemWriteCondition?

ArrayElement<InstanceType<T>[K]> extends object ? object & ArrayElement<InstanceType<T>[K]>[L] : ArrayElement<InstanceType<T>[K]> | null

Expected value for condition field on item

Returns

Promise<void>

Inherited from

CollectionOperations.upsertItemToCollection