From a30374e8e6b3e786ce8b349757625e8578eb296a Mon Sep 17 00:00:00 2001 From: Will Schurman Date: Mon, 16 Feb 2026 15:35:48 -0800 Subject: [PATCH] chore: docblock improvements --- packages/entity/src/EnforcingEntityCreator.ts | 2 +- packages/entity/src/Entity.ts | 6 +++++ packages/entity/src/EntityPrivacyPolicy.ts | 24 +++++++++++++++++++ .../src/internal/EntityLoadInterfaces.ts | 2 ++ 4 files changed, 33 insertions(+), 1 deletion(-) diff --git a/packages/entity/src/EnforcingEntityCreator.ts b/packages/entity/src/EnforcingEntityCreator.ts index 5bf3380a9..429930d14 100644 --- a/packages/entity/src/EnforcingEntityCreator.ts +++ b/packages/entity/src/EnforcingEntityCreator.ts @@ -6,7 +6,7 @@ import { ReadonlyEntity } from './ReadonlyEntity'; import { ViewerContext } from './ViewerContext'; /** - * Enforcing entity creator. All updates + * Enforcing entity creator. All creates * through this creator will throw if authorization is not successful. */ export class EnforcingEntityCreator< diff --git a/packages/entity/src/Entity.ts b/packages/entity/src/Entity.ts index ed47100d9..73b212f41 100644 --- a/packages/entity/src/Entity.ts +++ b/packages/entity/src/Entity.ts @@ -32,6 +32,12 @@ import { ViewerContext } from './ViewerContext'; * * All concrete entity implementations should extend this class and provide their * own EntityCompanionDefinition. + * + * Generic type parameters: + * TFields - the shape of the underlying data for this entity, typically corresponding to a database table schema. The mapping from TFields to the actual database schema is defined in the EntityCompanionDefinition for this entity. + * TIDField - the key of the ID field in TFields, which must be non-nullable and is used to uniquely identify individual entities + * TViewerContext - the type of ViewerContext that can be used with this entity + * TSelectedFields - the keys of fields in TFields that belong to this entity; used when there are multiple entities backed by the same underlying table with different field subsets */ export abstract class Entity< TFields extends Record, diff --git a/packages/entity/src/EntityPrivacyPolicy.ts b/packages/entity/src/EntityPrivacyPolicy.ts index 57aa51daa..f4782504c 100644 --- a/packages/entity/src/EntityPrivacyPolicy.ts +++ b/packages/entity/src/EntityPrivacyPolicy.ts @@ -123,6 +123,9 @@ export abstract class EntityPrivacyPolicy< TEntity extends ReadonlyEntity, TSelectedFields extends keyof TFields = keyof TFields, > { + /** + * List of rules to evaluate for create authorization. + */ protected readonly createRules: readonly PrivacyPolicyRule< TFields, TIDField, @@ -130,6 +133,10 @@ export abstract class EntityPrivacyPolicy< TEntity, TSelectedFields >[] = []; + + /** + * List of rules to evaluate for read authorization. + */ protected readonly readRules: readonly PrivacyPolicyRule< TFields, TIDField, @@ -137,6 +144,10 @@ export abstract class EntityPrivacyPolicy< TEntity, TSelectedFields >[] = []; + + /** + * List of rules to evaluate for update authorization. + */ protected readonly updateRules: readonly PrivacyPolicyRule< TFields, TIDField, @@ -144,6 +155,10 @@ export abstract class EntityPrivacyPolicy< TEntity, TSelectedFields >[] = []; + + /** + * List of rules to evaluate for delete authorization. + */ protected readonly deleteRules: readonly PrivacyPolicyRule< TFields, TIDField, @@ -156,6 +171,9 @@ export abstract class EntityPrivacyPolicy< * Get the privacy policy evaluation mode and deny handler for this policy. * Defaults to normal enforcing policy. * + * DRY_RUN mode is useful for testing and logging the effects of a policy without actually enforcing it, such as when + * first rolling out a new policy. Entities that fail the policy will be allowed so caution should be take when using. + * * @remarks * * Override to enable dry run evaluation of the policy. @@ -204,7 +222,9 @@ export abstract class EntityPrivacyPolicy< * Authorize an entity against read policy. * @param viewerContext - viewer context of user reading the entity * @param queryContext - query context in which to perform the read authorization + * @param evaluationContext - context about the reason for this privacy policy evaluation * @param entity - entity to authorize + * @param metricsAdapter - adapter for logging metrics about this authorization * @returns entity if authorized * @throws EntityNotAuthorizedError when not authorized */ @@ -236,7 +256,9 @@ export abstract class EntityPrivacyPolicy< * Authorize an entity against update policy. * @param viewerContext - viewer context of user updating the entity * @param queryContext - query context in which to perform the update authorization + * @param evaluationContext - context about the reason for this privacy policy evaluation * @param entity - entity to authorize + * @param metricsAdapter - adapter for logging metrics about this authorization * @returns entity if authorized * @throws EntityNotAuthorizedError when not authorized */ @@ -268,7 +290,9 @@ export abstract class EntityPrivacyPolicy< * Authorize an entity against deletion policy. * @param viewerContext - viewer context of user deleting the entity * @param queryContext - query context in which to perform the delete authorization + * @param evaluationContext - context about the reason for this privacy policy evaluation * @param entity - entity to authorize + * @param metricsAdapter - adapter for logging metrics about this authorization * @returns entity if authorized * @throws EntityNotAuthorizedError when not authorized */ diff --git a/packages/entity/src/internal/EntityLoadInterfaces.ts b/packages/entity/src/internal/EntityLoadInterfaces.ts index 78d82f601..193e681e9 100644 --- a/packages/entity/src/internal/EntityLoadInterfaces.ts +++ b/packages/entity/src/internal/EntityLoadInterfaces.ts @@ -3,6 +3,8 @@ import { ISerializable, SerializableKeyMap } from '../utils/collections/Serializ /** * Load method type identifier of a load key. Used for keying data loaders and identification in metrics. + * + * @internal */ export enum EntityLoadMethodType { /**