From 85f512f9bb3f622303b99de5aaf1282431b8bf44 Mon Sep 17 00:00:00 2001 From: DylanBulmer Date: Sun, 21 Jul 2024 09:17:21 -0400 Subject: [PATCH] document Base and User entities --- README.md | 2 +- deno.json | 2 +- deno.lock | 15 +++++++++--- mod.ts | 25 +++++++++++++++++++ src/mod.ts | 25 ------------------- src/models/Annotation.ts | 4 +-- src/models/Authorization.ts | 4 +-- src/models/Base.ts | 34 +++++++++++++++++-------- src/models/Dataset.ts | 4 +-- src/models/Group.ts | 4 +-- src/models/Message.ts | 4 +-- src/models/Organization.ts | 4 +-- src/models/Profile.ts | 4 +-- src/models/Project.ts | 4 +-- src/models/Role.ts | 4 +-- src/models/Sample.ts | 4 +-- src/models/User.ts | 49 +++++++++++++++++++++++++------------ src/models/UserGroup.ts | 4 +-- src/types/User.ts | 10 ++++---- 19 files changed, 123 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index fc4c184..b8a433e 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ import { User } from "jsr:@codr/models@^1"; ```bash # Clone the repo -git clone git@github.com:CodrJS/models.git +git clone git@github.com:CodrJS/jsr-models.git # Cache deno dependencies deno cache ./mod.ts diff --git a/deno.json b/deno.json index 7ee580d..0287b10 100644 --- a/deno.json +++ b/deno.json @@ -10,7 +10,7 @@ "singleQuote": false }, "publish": { - "exclude": [".github/*", "tests/*.test.ts", ".gitignore"] + "exclude": [".github/*", "tests/*.test.ts", ".gitignore", "coverage/*"] }, "imports": { "@std/assert": "jsr:@std/assert@^1.0.0", diff --git a/deno.lock b/deno.lock index 29d8b33..21abb02 100644 --- a/deno.lock +++ b/deno.lock @@ -2,10 +2,10 @@ "version": "3", "packages": { "specifiers": { - "jsr:@std/assert": "jsr:@std/assert@1.0.0", + "jsr:@std/assert@^1.0.0": "jsr:@std/assert@1.0.0", "jsr:@std/internal@^1.0.1": "jsr:@std/internal@1.0.1", - "npm:bson": "npm:bson@6.8.0", - "npm:jsonwebtoken": "npm:jsonwebtoken@9.0.2" + "npm:bson@^6.8.0": "npm:bson@6.8.0", + "npm:jsonwebtoken@^9.0.2": "npm:jsonwebtoken@9.0.2" }, "jsr": { "@std/assert@1.0.0": { @@ -105,5 +105,12 @@ } } }, - "remote": {} + "remote": {}, + "workspace": { + "dependencies": [ + "jsr:@std/assert@^1.0.0", + "npm:bson@^6.8.0", + "npm:jsonwebtoken@^9.0.2" + ] + } } diff --git a/mod.ts b/mod.ts index a1ca67a..b04e8e5 100644 --- a/mod.ts +++ b/mod.ts @@ -1 +1,26 @@ +/** + * @module + * + * This module consists of class entities used to collect, transform, and + * process data in Codr. + * + * @example + * ```ts + * import { Organization } from "@codr/models"; + * import { ObjectId } from "bson"; + * + * const org = new Organization ({ + * name: "Demo Organization", + * domains: ["localhost:3000"], + * flags: { + * isActive: true, + * isDeleted: false, + * isDemo: true, + * }, + * slug: "demo", + * createdBy: new ObjectId(), + * }) + * ``` + */ + export * from "./src/mod.ts"; diff --git a/src/mod.ts b/src/mod.ts index 38b9724..0ce6f2a 100644 --- a/src/mod.ts +++ b/src/mod.ts @@ -1,27 +1,2 @@ -/** - * @module - * - * This module consists of class entities used to collect, transform, and - * process data in Codr. - * - * @example - * ```ts - * import { Organization } from "@codr/models"; - * import { ObjectId } from "bson"; - * - * const org = new Organization ({ - * name: "Demo Organization", - * domains: ["localhost:3000"], - * flags: { - * isActive: true, - * isDeleted: false, - * isDemo: true, - * }, - * slug: "demo", - * createdBy: new ObjectId(), - * }) - * ``` - */ - // export * as Types from "./types/mod.ts"; export * from "./models/mod.ts"; diff --git a/src/models/Annotation.ts b/src/models/Annotation.ts index b0a3b9c..205b1c8 100644 --- a/src/models/Annotation.ts +++ b/src/models/Annotation.ts @@ -24,7 +24,7 @@ export class Annotation extends Base<"Annotation"> { value, annotatedBy, _id, - __v, + _version, createdAt, updatedAt, createdBy, @@ -38,7 +38,7 @@ export class Annotation extends Base<"Annotation"> { | "sampleId" | "value" >) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.projectId = projectId; this.datasetId = datasetId; this.value = value; diff --git a/src/models/Authorization.ts b/src/models/Authorization.ts index 00cbb3f..90b4c45 100644 --- a/src/models/Authorization.ts +++ b/src/models/Authorization.ts @@ -21,13 +21,13 @@ export class Authorization extends Base<"Authorization"> { userId, roleId = [], _id, - __v, + _version, createdAt, updatedAt, createdBy, updatedBy, }: AtLeast) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.userId = userId; this.roleId = roleId; } diff --git a/src/models/Base.ts b/src/models/Base.ts index fc06db3..f9cddb1 100644 --- a/src/models/Base.ts +++ b/src/models/Base.ts @@ -1,23 +1,33 @@ import { ObjectId } from "bson"; import type { AtLeast } from "../types/mod.ts"; +/** + * Base entity parameters for all database entities. + */ export interface IBase { + /** Typescript annotation for permissioning/authorization purposes. */ readonly kind: Kind; - __v?: number; + /** Entity version stored in the database. */ + _version?: number; + /** Entity identifier stored in the database. */ _id: ObjectId; + /** Entity created date. */ createdAt: Date; + /** Entity unpdated date. */ updatedAt: Date; + /** Entity created by {@link User} id. */ createdBy: ObjectId; + /** Entity updated by {@link User} id. */ updatedBy: ObjectId; } export class Base { - readonly __v: IBase["__v"]; + readonly _version: IBase["_version"]; readonly _id: IBase["_id"]; - readonly createdAt: Date; - readonly updatedAt: Date; - readonly createdBy: ObjectId; - readonly updatedBy: ObjectId; + readonly createdAt: IBase["createdAt"]; + readonly updatedAt: IBase["updatedAt"]; + readonly createdBy: IBase["createdBy"]; + readonly updatedBy: IBase["updatedBy"]; constructor({ createdAt, @@ -25,12 +35,12 @@ export class Base { createdBy, updatedBy, _id, - __v, + _version = 0, }: AtLeast, "createdBy">) { - this.__v = __v; + this._version = _version; this._id = _id || new ObjectId(); - const now = new Date(Date.now()); + const now = new Date(); this.createdAt = createdAt || now; this.updatedAt = updatedAt || now; @@ -38,9 +48,13 @@ export class Base { this.updatedBy = updatedBy || createdBy; } + /** + * Transforms the base class object into a json object. Useful for saving the entity to the database. + * @returns a json representation of the base entity. + */ toJSON(): Omit, "kind"> { return { - __v: this.__v, + _version: this._version, _id: this._id, createdAt: this.createdAt, updatedAt: this.updatedAt, diff --git a/src/models/Dataset.ts b/src/models/Dataset.ts index f8e0b86..0276e0c 100644 --- a/src/models/Dataset.ts +++ b/src/models/Dataset.ts @@ -17,7 +17,7 @@ export class Dataset extends Base<"Dataset"> { flags, projectId, _id, - __v, + _version, createdAt, updatedAt, name, @@ -26,7 +26,7 @@ export class Dataset extends Base<"Dataset"> { }: AtLeast) { super({ _id, - __v, + _version, createdAt, updatedAt, createdBy, diff --git a/src/models/Group.ts b/src/models/Group.ts index 871e876..8ebd668 100644 --- a/src/models/Group.ts +++ b/src/models/Group.ts @@ -34,13 +34,13 @@ export class Group< members, flags, _id, - __v, + _version, createdAt, updatedAt, createdBy, updatedBy, }: AtLeast, "createdBy" | "name" | "members" | "flags">) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.name = name; this.members = members; this.flags = flags; diff --git a/src/models/Message.ts b/src/models/Message.ts index be97121..717f468 100644 --- a/src/models/Message.ts +++ b/src/models/Message.ts @@ -21,13 +21,13 @@ export class Message extends Base<"Message"> { body, to, _id, - __v, + _version, createdAt, updatedAt, createdBy, updatedBy, }: AtLeast) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.body = body; this.subject = subject; this.to = to; diff --git a/src/models/Organization.ts b/src/models/Organization.ts index c24dc79..64a5224 100644 --- a/src/models/Organization.ts +++ b/src/models/Organization.ts @@ -47,7 +47,7 @@ export class Organization extends Base<"Organization"> { isDemo: false, }, _id, - __v, + _version, createdAt, updatedAt, createdBy, @@ -58,7 +58,7 @@ export class Organization extends Base<"Organization"> { }: AtLeast) { super({ _id, - __v, + _version, createdAt, updatedAt, createdBy, diff --git a/src/models/Profile.ts b/src/models/Profile.ts index 4012da2..d222e63 100644 --- a/src/models/Profile.ts +++ b/src/models/Profile.ts @@ -34,7 +34,7 @@ export class Profile extends Base<"Profile"> { userId, phone, _id, - __v, + _version, user, createdAt, updatedAt, @@ -44,7 +44,7 @@ export class Profile extends Base<"Profile"> { IProfile & { user: User }, "createdBy" | "name" | "userId" | "username" >) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.name = name; this.avatarUrl = avatarUrl; this.userId = userId; diff --git a/src/models/Project.ts b/src/models/Project.ts index cc8464c..55d3352 100644 --- a/src/models/Project.ts +++ b/src/models/Project.ts @@ -34,7 +34,7 @@ export class Project extends Base<"Project"> { name, type, _id, - __v, + _version, createdAt, updatedAt, createdBy, @@ -43,7 +43,7 @@ export class Project extends Base<"Project"> { IProject, "createdBy" | "bgColorClass" | "config" | "flags" | "slug" | "name" | "type" >) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.bgColorClass = bgColorClass; this.config = config; diff --git a/src/models/Role.ts b/src/models/Role.ts index 5839778..8a2923e 100644 --- a/src/models/Role.ts +++ b/src/models/Role.ts @@ -33,7 +33,7 @@ export class Role extends Base<"Role"> { description, grants, _id, - __v, + _version, createdAt, updatedAt, createdBy, @@ -42,7 +42,7 @@ export class Role extends Base<"Role"> { IRole & { user: User }, "createdBy" | "name" | "code" | "description" | "grants" >) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.name = name; this.code = code; this.description = description; diff --git a/src/models/Sample.ts b/src/models/Sample.ts index 415fe09..109f72d 100644 --- a/src/models/Sample.ts +++ b/src/models/Sample.ts @@ -18,13 +18,13 @@ export class Sample extends Base<"Smaple"> { datasetId, payload, _id, - __v, + _version, createdAt, updatedAt, createdBy, updatedBy, }: AtLeast) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.projectId = projectId; this.datasetId = datasetId; this.payload = payload; diff --git a/src/models/User.ts b/src/models/User.ts index ee87944..afa57df 100644 --- a/src/models/User.ts +++ b/src/models/User.ts @@ -1,53 +1,72 @@ import { Base, type IBase } from "./Base.ts"; -import type { AtLeast, UserEnum } from "../types/mod.ts"; +import type { AtLeast, UserTypeCode } from "../types/mod.ts"; import type { ObjectId } from "bson"; +/** + * User entity parameters for creating a {@link User} entity. + */ export interface IUser extends IBase<"User"> { + /** Identifier from identitity provider. */ + identityId: string; + /** The organization id the user belongs to. */ organizationId: ObjectId; - type: UserEnum; + /** Type of user from {@link UserTypeCode} */ + type: UserTypeCode; + /** Email address used to signin, used for notification purposes only.*/ email: string; + /** User flags */ flags: { + /** Is the user anonymous (primarily used for annotator accounts) */ isAnonymous: boolean; + /** Is the user soft deleted */ isDeleted: boolean; - isDisabled: boolean; + /** Is the user account active or disabled */ + isActive: boolean; }; } +/** + * User entity class for representing a user account. + */ export class User extends Base<"User"> { - organizationId: ObjectId; - type: UserEnum; - email: string; - flags: { - isAnonymous: boolean; - isDeleted: boolean; - isDisabled: boolean; - }; + identityId: IUser["identityId"]; + organizationId: IUser["organizationId"]; + type: IUser["type"]; + email: IUser["email"]; + flags: IUser["flags"]; constructor({ + identityId, organizationId, type, email, - flags = { isDisabled: false, isAnonymous: false, isDeleted: false }, + flags = { isActive: false, isAnonymous: false, isDeleted: false }, _id, - __v, + _version, createdAt, updatedAt, createdBy, updatedBy, }: AtLeast< IUser, - "createdBy" | "type" | "email" | "flags" | "organizationId" + "createdBy" | "type" | "email" | "flags" | "organizationId" | "identityId" >) { - super({ _id, __v, createdAt, updatedAt, createdBy, updatedBy }); + super({ _id, _version, createdAt, updatedAt, createdBy, updatedBy }); this.type = type; this.email = email; this.flags = flags; this.organizationId = organizationId; + this.identityId = identityId; } + /** + * Transforms the user class object into a json object. Useful for saving the entity to the database. + * @returns a json representation of the user account. + */ toJSON(): Omit { const json = super.toJSON(); return { + identityId: this.identityId, organizationId: this.organizationId, type: this.type, email: this.email, diff --git a/src/models/UserGroup.ts b/src/models/UserGroup.ts index f47d237..9068411 100644 --- a/src/models/UserGroup.ts +++ b/src/models/UserGroup.ts @@ -18,7 +18,7 @@ export class UserGroup extends Group<"UserGroup", UserGroupFlags> { isPrivate: false, }, _id, - __v, + _version, createdAt, updatedAt, createdBy, @@ -28,7 +28,7 @@ export class UserGroup extends Group<"UserGroup", UserGroupFlags> { }: IUserGroup) { super({ _id, - __v, + _version, createdAt, updatedAt, createdBy, diff --git a/src/types/User.ts b/src/types/User.ts index 6ecb6c0..4f0c033 100644 --- a/src/types/User.ts +++ b/src/types/User.ts @@ -1,7 +1,7 @@ export type UserType = "ANONYMOUS" | "MEMBER" | "EXTERNAL" | "SYSTEM"; -export enum UserEnum { - ANONYMOUS = "Anonymous", - MEMBER = "Member", - EXTERNAL = "External", - SYSTEM = "System", +export enum UserTypeCode { + Anonymous = "ANONYMOUS", + Member = "MEMBER", + External = "EXTERNAL", + System = "SYSTEM", }