UNPKG

@clickup/ent-framework

Version:

A PostgreSQL graph-database-alike library with microsharding and row-level security

531 lines (310 loc) 13.1 kB
[**@clickup/ent-framework**](../README.md) *** [@clickup/ent-framework](../globals.md) / VC # Class: VC Defined in: [src/ent/VC.ts:47](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L47) VC - Viewer Context. VC is set per HTTP request (or per worker job) in each Ent and represents the person who is about to run some database operation. It can represent a user, or a guest, or a bot observing that Ent. Depending on the Ent's Configuration object and privacy rules, it may allow the user to load/insert/update/etc. or to traverse to related objects. ## Properties | Property | Type | Description | | ------ | ------ | ------ | | <a id="principal"></a> `principal` | `string` | A principal (typically user ID) represented by this VC. | | <a id="freshness"></a> `freshness` | `null` \| *typeof* [`MASTER`](../variables/MASTER.md) \| *typeof* [`STALE_REPLICA`](../variables/STALE_REPLICA.md) | Allows to set VC to always use either a master or a replica DB. E.g. if freshness=MASTER, then all the timeline data is ignored, and all the requests are sent to master. | | <a id="heartbeater"></a> `heartbeater` | `object` | The heartbeat callback is called before each primitive operation. It plays the similar role as AbortController: when called, it may throw sometimes (signalled externally). Delay callback can also be passed since it's pretty common use case to wait for some time and be aborted on a heartbeat exception. | | `heartbeater.heartbeat` | () => `Promise`\<`void`\> | - | | `heartbeater.delay` | (`ms`: `number`) => `Promise`\<`void`\> | - | ## Methods ### createGuestPleaseDoNotUseCreationPointsMustBeLimited() > `static` **createGuestPleaseDoNotUseCreationPointsMustBeLimited**(`__namedParameters`): [`VC`](VC.md) Defined in: [src/ent/VC.ts:70](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L70) Please please don't call this method except one or two core places. The idea is that we create an "origin" VC once and then derive all other VCs from it (possibly upgrading or downgrading permissions, controlling master/replica read policy etc.). It's also good to trace the entire chain of calls and reasons, why some object was accessed. #### Parameters | Parameter | Type | | ------ | ------ | | `__namedParameters` | \{ `trace`: `string`; `cachesExpirationMs`: `number`; \} | | `__namedParameters.trace`? | `string` | | `__namedParameters.cachesExpirationMs`? | `number` | #### Returns [`VC`](VC.md) *** ### \[custom\]() > **\[custom\]**(): `string` Defined in: [src/ent/VC.ts:92](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L92) This is to show VCs in console.log() and inspect() nicely. #### Returns `string` *** ### cache() #### Call Signature > **cache**\<`TInstance`\>(`Class`): `TInstance` Defined in: [src/ent/VC.ts:100](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L100) Some IDs are cached in VC (e.g. is this ID readable? is it writable? is this VC an admin VC?). Also, people may define their own VC-local caches. ##### Type Parameters | Type Parameter | | ------ | | `TInstance` | ##### Parameters | Parameter | Type | | ------ | ------ | | `Class` | (`vc`) => `TInstance` | ##### Returns `TInstance` #### Call Signature > **cache**\<`TInstance`\>(`tag`, `creator`): `TInstance` Defined in: [src/ent/VC.ts:106](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L106) Same as the above overload, but allows to use a custom creating function. This is useful when e.g. cached values are async-created. ##### Type Parameters | Type Parameter | | ------ | | `TInstance` | ##### Parameters | Parameter | Type | | ------ | ------ | | `tag` | `symbol` | | `creator` | (`vc`) => `TInstance` | ##### Returns `TInstance` *** ### loader() > **loader**\<`TLoadArgs`, `TReturn`\>(`HandlerClass`): [`Loader`](Loader.md)\<`TLoadArgs`, `TReturn`\> Defined in: [src/ent/VC.ts:131](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L131) Returns a cached instance of Loader whose actual code is defined in HandlerClass. In case there is no such Loader yet, creates it. #### Type Parameters | Type Parameter | | ------ | | `TLoadArgs` *extends* `unknown`[] | | `TReturn` | #### Parameters | Parameter | Type | | ------ | ------ | | `HandlerClass` | (`vc`) => [`Handler`](../interfaces/Handler.md)\<`TLoadArgs`, `TReturn`\> | | `HandlerClass.$loader`? | `symbol` | #### Returns [`Loader`](Loader.md)\<`TLoadArgs`, `TReturn`\> *** ### timeline() > **timeline**(`shard`, `schemaName`): [`Timeline`](Timeline.md) Defined in: [src/ent/VC.ts:147](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L147) Returns Shard+schemaName timeline which tracks replica staleness for the particular schema name (most likely, table). #### Parameters | Parameter | Type | | ------ | ------ | | `shard` | [`Shard`](Shard.md)\<[`Client`](Client.md)\> | | `schemaName` | `string` | #### Returns [`Timeline`](Timeline.md) *** ### serializeTimelines() > **serializeTimelines**(): `undefined` \| `string` Defined in: [src/ent/VC.ts:163](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L163) Serializes Shard timelines (master WAL positions) to a string format. The method always returns a value which is compatible to deserializeTimelines() input. #### Returns `undefined` \| `string` *** ### deserializeTimelines() > **deserializeTimelines**(...`dataStrs`): [`VC`](VC.md) Defined in: [src/ent/VC.ts:195](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L195) Restores all replication timelines in the VC based on the serialized info provided. Returns the new VC derived from the current one, but with empty caches. This method has a side effect of changing the timelines of the current VC (and actually all parent VCs), because it reflects the changes in the global DB state as seen by the current VC's principal. It restores previously serialized timelines to the existing VC and all its parent VCs which share the same principal. (The latter happens, because `this.timelines` map is passed by reference to all derived VCs starting from the one which sets principal; see `new VC(...)` clauses all around and toLowerInternal() logic.) The timelines are merged according to WAL positions (larger WAL positions win). #### Parameters | Parameter | Type | | ------ | ------ | | ...`dataStrs` | readonly (`undefined` \| `string`)[] | #### Returns [`VC`](VC.md) *** ### withEmptyCache() > **withEmptyCache**(): [`VC`](VC.md) Defined in: [src/ent/VC.ts:217](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L217) Returns a new VC derived from the current one, but with empty cache. #### Returns [`VC`](VC.md) *** ### withTransitiveMasterFreshness() > **withTransitiveMasterFreshness**(): [`VC`](VC.md) Defined in: [src/ent/VC.ts:234](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L234) Returns a new VC derived from the current one, but with master freshness. Master freshness is inherited by ent.vc after an Ent is loaded. #### Returns [`VC`](VC.md) *** ### withOneTimeStaleReplica() > **withOneTimeStaleReplica**(): [`VC`](VC.md) Defined in: [src/ent/VC.ts:261](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L261) Returns a new VC derived from the current one, but which forces an Ent to be loaded always from replica. Freshness is NOT inherited by Ents (not transitive): e.g. if an Ent is loaded with STALE_REPLICA freshness, its ent.vc will have the DEFAULT freshness. Also, if an Ent is inserted with a VC of STALE_REPLICA freshness, its VC won't remember it, so next immediate reads will go to a replica and not to the master. #### Returns [`VC`](VC.md) *** ### withDefaultFreshness() > **withDefaultFreshness**(): [`VC`](VC.md) Defined in: [src/ent/VC.ts:284](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L284) Creates a new VC with default freshness (i.e. not sticky to master or replica, auto-detected on request). Generally, it's not a good idea to use this derivation since we lose some bit of internal knowledge from the past history of the VC, but for e.g. tests or benchmarks, it's fine. #### Returns [`VC`](VC.md) *** ### withFlavor() #### Call Signature > **withFlavor**(`prepend`, ...`flavors`): `this` Defined in: [src/ent/VC.ts:305](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L305) Returns a new VC derived from the current one adding some more flavors to it. If no flavors were added, returns the same VC (`this`). ##### Parameters | Parameter | Type | | ------ | ------ | | `prepend` | `"prepend"` | | ...`flavors` | (`undefined` \| [`VCFlavor`](VCFlavor.md))[] | ##### Returns `this` #### Call Signature > **withFlavor**(...`flavors`): `this` Defined in: [src/ent/VC.ts:306](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L306) Returns a new VC derived from the current one adding some more flavors to it. If no flavors were added, returns the same VC (`this`). ##### Parameters | Parameter | Type | | ------ | ------ | | ...`flavors` | (`undefined` \| [`VCFlavor`](VCFlavor.md))[] | ##### Returns `this` *** ### withNewTrace() > **withNewTrace**(`trace`): [`VC`](VC.md) Defined in: [src/ent/VC.ts:343](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L343) Derives the VC with new trace ID. #### Parameters | Parameter | Type | | ------ | ------ | | `trace` | `undefined` \| `string` | #### Returns [`VC`](VC.md) *** ### withHeartbeater() > **withHeartbeater**(`heartbeater`): [`VC`](VC.md) Defined in: [src/ent/VC.ts:359](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L359) Derives the VC with the provided heartbeater injected. #### Parameters | Parameter | Type | | ------ | ------ | | `heartbeater` | \{ `heartbeat`: () => `Promise`\<`void`\>; `delay`: (`ms`) => `Promise`\<`void`\>; \} | | `heartbeater.heartbeat` | () => `Promise`\<`void`\> | | `heartbeater.delay` | (`ms`) => `Promise`\<`void`\> | #### Returns [`VC`](VC.md) *** ### toOmniDangerous() > **toOmniDangerous**(): [`VC`](VC.md) Defined in: [src/ent/VC.ts:379](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L379) Creates a new VC upgraded to omni permissions. This VC will not be placed to some Ent's ent.vc property; instead, it will be automatically downgraded to either the owning VC of this Ent or to a guest VC (see Ent.ts). #### Returns [`VC`](VC.md) *** ### toGuest() > **toGuest**(): [`VC`](VC.md) Defined in: [src/ent/VC.ts:396](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L396) Creates a new VC downgraded to guest permissions. #### Returns [`VC`](VC.md) *** ### isOmni() > **isOmni**(): `boolean` Defined in: [src/ent/VC.ts:411](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L411) Checks if it's an omni VC. #### Returns `boolean` *** ### isGuest() > **isGuest**(): `boolean` Defined in: [src/ent/VC.ts:418](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L418) Checks if it's a guest VC. #### Returns `boolean` *** ### isLoggedIn() > **isLoggedIn**(): `boolean` Defined in: [src/ent/VC.ts:425](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L425) Checks if it's a regular user (i.e. owning) VC. #### Returns `boolean` *** ### flavor() > **flavor**\<`TFlavor`\>(`flavor`): `null` \| `TFlavor` Defined in: [src/ent/VC.ts:432](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L432) Returns VC's flavor of the particular type. #### Type Parameters | Type Parameter | | ------ | | `TFlavor` *extends* [`VCFlavor`](VCFlavor.md) | #### Parameters | Parameter | Type | | ------ | ------ | | `flavor` | (...`args`) => `TFlavor` | #### Returns `null` \| `TFlavor` *** ### toString() > **toString**(`withInstanceNumber`): `string` Defined in: [src/ent/VC.ts:441](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L441) Used for debugging purposes. #### Parameters | Parameter | Type | Default value | | ------ | ------ | ------ | | `withInstanceNumber` | `boolean` | `false` | #### Returns `string` *** ### toAnnotation() > **toAnnotation**(): [`QueryAnnotation`](../interfaces/QueryAnnotation.md) Defined in: [src/ent/VC.ts:460](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L460) Returns a debug annotation of this VC. #### Returns [`QueryAnnotation`](../interfaces/QueryAnnotation.md) *** ### toLowerInternal() > **toLowerInternal**(`principal`): [`VC`](VC.md) Defined in: [src/ent/VC.ts:491](https://github.com/clickup/ent-framework/blob/master/src/ent/VC.ts#L491) Used internally by Ent framework to lower permissions of an injected VC. For guest, principal === null. - freshness is always reset to default one it VC is demoted - isRoot is changed to false once a root VC is switched to a per-user VC #### Parameters | Parameter | Type | | ------ | ------ | | `principal` | `null` \| `string` | #### Returns [`VC`](VC.md)