Skip to content

Commit

Permalink
add JSDocs for functions
Browse files Browse the repository at this point in the history
  • Loading branch information
@sugat009
sugat009 committed Nov 18, 2024
1 parent bb98dcf commit 43efbef
Show file tree
Hide file tree
Showing 5 changed files with 86 additions and 32 deletions.
16 changes: 8 additions & 8 deletions shared-libs/cht-datasource/src/contact.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,17 +34,17 @@ export namespace v1 {
readonly parent?: NormalizedParent;
}

/** @internal */
/** @ignore */
export const isNormalizedParent = (value: unknown): value is NormalizedParent => {
return isDataObject(value) && isIdentifiable(value) && (!value.parent || isNormalizedParent(value.parent));
};

/** @internal */
/** @ignore */
export const isContactType = (value: ContactTypeQualifier | FreetextQualifier): value is ContactTypeQualifier => {
return 'contactType' in value;
};

/** @internal */
/** @ignore */
export const isFreetextType = (value: ContactTypeQualifier | FreetextQualifier): value is FreetextQualifier => {
return 'freetext' in value;
};
Expand All @@ -71,7 +71,7 @@ export namespace v1 {
}
};

/** @internal */
/** @ignore */
export const createQualifier = (
freetext: Nullable<string> = null,
type: Nullable<string> = null
Expand Down Expand Up @@ -151,9 +151,9 @@ export namespace v1 {
* returned. Subsequent pages can be retrieved by providing the cursor returned with the previous page.
* @param limit the maximum number of identifiers to return. Default is 10000.
* @returns a page of contact identifiers for the provided specification
* @throws Error if no qualifier is provided or if the qualifier is invalid
* @throws Error if the provided `limit` value is `<=0`
* @throws Error if the provided cursor is not a valid page token or `null`
* @throws InvalidArrgumentError if no qualifier is provided or if the qualifier is invalid
* @throws InvalidArgumentError if the provided `limit` value is `<=0`
* @throws InvalidArgumentError if the provided cursor is not a valid page token or `null`
*/
const curriedFn = async (
qualifier: ContactTypeQualifier | FreetextQualifier,
Expand Down Expand Up @@ -190,7 +190,7 @@ export namespace v1 {
* Returns a generator for fetching all contact identifiers that match the given qualifier
* @param qualifier the limiter defining which identifiers to return
* @returns a generator for fetching all contact identifiers that match the given qualifier
* @throws Error if no qualifier is provided or if the qualifier is invalid
* @throws InvalidArgumentError if no qualifier is provided or if the qualifier is invalid
*/
const curriedGen = (
qualifier: ContactTypeQualifier | FreetextQualifier
Expand Down
75 changes: 64 additions & 11 deletions shared-libs/cht-datasource/src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,13 +59,35 @@ export const getDatasource = (ctx: DataContext) => {
hasPermissions,
hasAnyPermission,
contact: {
/** TODO */
/**
* Returns a contact by their UUID.
* @param uuid the UUID of the contact to retrieve
* @returns the contact or `null` if no contact is found for the UUID
* @throws InvalidArgumentError if no UUID is provided
*/
getByUuid: (uuid: string) => ctx.bind(Contact.v1.get)(Qualifier.byUuid(uuid)),

/** TODO */
/**
* Returns a contact by their UUID along with the contact's parent lineage.
* @param uuid the UUID of the contact to retrieve
* @returns the contact or `null` if no contact is found the UUID
* @throws InvalidArgumentError if no UUID is provided
*/
getByUuidWithLineage: (uuid: string) => ctx.bind(Contact.v1.getWithLineage)(Qualifier.byUuid(uuid)),

/** TODO */
/**
* Returns an array of contact identifiers for the provided page specifications.
* @param freetext the search keyword(s)
* @param type the type of contact to search for
* @param cursor the token identifying which page to retrieve. A `null` value indicates the first page should be
* returned. Subsequent pages can be retrieved by providing the cursor returned with the previous page.
* @param limit the maximum number of identifiers to return. Default is 10000.
* @returns a page of contact identifiers for the provided specifications
* @throws InvalidArgumentError if either `freetext` or `type` is not provided
* @throws InvalidArgumentError if the `freetext` is empty or if the `type is invalid for a contact
* @throws InvalidArgumentError if the provided limit is `<= 0`
* @throws InvalidArgumentError if the provided cursor is not a valid page token or `null`
*/
getIdsPage: (
freetext: Nullable<string> = null,
type: Nullable<string> = null,
Expand All @@ -75,7 +97,15 @@ export const getDatasource = (ctx: DataContext) => {
Contact.v1.createQualifier(freetext, type), cursor, limit
),

/** TODO */
/**
* Returns a generator for fetching all the contact identifiers for given
* `freetext` and `type`.
* @param freetext the search keyword(s)
* @param type the type of contact identifiers to return
* @returns a generator for fetching all the contact identifiers matching the given `freetext` and `type`.
* @throws InvalidArgumentError if either `freetext` or `type` is not provided
* @throws InvalidArgumentError if the `freetext` is empty or if the `type is invalid for a contact
*/
getIds: (
freetext: Nullable<string> = null,
type: Nullable<string> = null
Expand All @@ -86,15 +116,15 @@ export const getDatasource = (ctx: DataContext) => {
* Returns a place by its UUID.
* @param uuid the UUID of the place to retrieve
* @returns the place or `null` if no place is found for the UUID
* @throws Error if no UUID is provided
* @throws InvalidArgumentError if no UUID is provided
*/
getByUuid: (uuid: string) => ctx.bind(Place.v1.get)(Qualifier.byUuid(uuid)),

/**
* Returns a place by its UUID along with the place's parent lineage.
* @param uuid the UUID of the place to retrieve
* @returns the place or `null` if no place is found for the UUID
* @throws Error if no UUID is provided
* @throws InvalidArgumentError if no UUID is provided
*/
getByUuidWithLineage: (uuid: string) => ctx.bind(Place.v1.getWithLineage)(Qualifier.byUuid(uuid)),

Expand Down Expand Up @@ -131,15 +161,15 @@ export const getDatasource = (ctx: DataContext) => {
* Returns a person by their UUID.
* @param uuid the UUID of the person to retrieve
* @returns the person or `null` if no person is found for the UUID
* @throws Error if no UUID is provided
* @throws InvalidArgumentError if no UUID is provided
*/
getByUuid: (uuid: string) => ctx.bind(Person.v1.get)(Qualifier.byUuid(uuid)),

/**
* Returns a person by their UUID along with the person's parent lineage.
* @param uuid the UUID of the person to retrieve
* @returns the person or `null` if no person is found for the UUID
* @throws Error if no UUID is provided
* @throws InvalidArgumentError if no UUID is provided
*/
getByUuidWithLineage: (uuid: string) => ctx.bind(Person.v1.getWithLineage)(Qualifier.byUuid(uuid)),

Expand Down Expand Up @@ -172,21 +202,44 @@ export const getDatasource = (ctx: DataContext) => {
getByType: (personType: string) => ctx.bind(Person.v1.getAll)(Qualifier.byContactType(personType)),
},
report: {
/** TODO */
/**
* Returns a report by their UUID.
* @param uuid the UUID of the report to retrieve
* @returns the report or `null` if no report is found for the UUID
* @throws InvalidArgumentError if no UUID is provided
*/
// eslint-disable-next-line compat/compat
getByUuid: (uuid: string) => ctx.bind(Report.v1.get)(Qualifier.byUuid(uuid)),

/** TODO */
/**
* Returns a paged array of report identifiers from the given data context.
* @param qualifier the limiter defining which identifiers to return
* @param cursor the token identifying which page to retrieve. A `null` value indicates the first page should be
* returned. Subsequent pages can be retrieved by providing the cursor returned with the previous page.
* @param limit the maximum number of identifiers to return. Default is 10000.
* @returns a page of report identifiers for the provided specification
* @throws InvalidArgumentError if no qualifier is provided or if the qualifier is invalid
* @throws InvalidArgumentError if the provided `limit` value is `<=0`
* @throws InvalidArgumentError if the provided cursor is not a valid page token or `null`
*/
getIdsPage: (
qualifier: string,
cursor: Nullable<string> = null,
limit = 100
// eslint-disable-next-line compat/compat
) => ctx.bind(Report.v1.getIdsPage)(
Qualifier.byFreetext(qualifier), cursor, limit
),

/** TODO */
/**
* Returns a generator for fetching all the contact identifiers for given qualifier
* @param qualifier the limiter defining which identifiers to return
* @returns a generator for fetching all report identifiers that match the given qualifier
* @throws InvalidArgumentError if no qualifier is provided or if the qualifier is invalid
*/
getIds: (
qualifier: string,
// eslint-disable-next-line compat/compat
) => ctx.bind(Report.v1.getIdsAll)(Qualifier.byFreetext(qualifier)),
},
},
Expand Down
8 changes: 4 additions & 4 deletions shared-libs/cht-datasource/src/person.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,9 @@ export namespace v1 {
* returned. Subsequent pages can be retrieved by providing the cursor returned with the previous page.
* @param limit the maximum number of people to return. Default is 100.
* @returns a page of people for the provided specification
* @throws Error if no type is provided or if the type is not for a person
* @throws Error if the provided `limit` value is `<=0`
* @throws Error if the provided cursor is not a valid page token or `null`
* @throws InvalidArgumentError if no type is provided or if the type is not for a person
* @throws InvalidArgumentError if the provided `limit` value is `<=0`
* @throws InvalidArgumentError if the provided cursor is not a valid page token or `null`
*/
const curriedFn = async (
personType: ContactTypeQualifier,
Expand Down Expand Up @@ -113,7 +113,7 @@ export namespace v1 {
* Returns a generator for fetching all people with the given type
* @param personType the type of people to return
* @returns a generator for fetching all people with the given type
* @throws Error if no type is provided or if the type is not for a person
* @throws InvalidArgumentError if no type is provided or if the type is not for a person
*/
const curriedGen = (personType: ContactTypeQualifier): AsyncGenerator<Person, null> => {
assertTypeQualifier(personType);
Expand Down
11 changes: 6 additions & 5 deletions shared-libs/cht-datasource/src/place.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import { adapt, assertDataContext, DataContext } from './libs/data-context';
import * as Local from './local';
import * as Remote from './remote';
import { assertCursor, assertLimit, assertTypeQualifier, getPagedGenerator, Nullable, Page } from './libs/core';
import { InvalidArgumentError } from './libs/error';

/** */
export namespace v1 {
Expand All @@ -29,7 +30,7 @@ export namespace v1 {

const assertPlaceQualifier: (qualifier: unknown) => asserts qualifier is UuidQualifier = (qualifier: unknown) => {
if (!isUuidQualifier(qualifier)) {
throw new Error(`Invalid identifier [${JSON.stringify(qualifier)}].`);
throw new InvalidArgumentError(`Invalid identifier [${JSON.stringify(qualifier)}].`);
}
};

Expand Down Expand Up @@ -80,9 +81,9 @@ export namespace v1 {
* returned. Subsequent pages can be retrieved by providing the cursor returned with the previous page.
* @param limit the maximum number of places to return. Default is 100.
* @returns a page of places for the provided specification
* @throws Error if no type is provided or if the type is not for a place
* @throws Error if the provided `limit` value is `<=0`
* @throws Error if the provided cursor is not a valid page token or `null`
* @throws InvalidArgumentError if no type is provided or if the type is not for a place
* @throws InvalidArgumentError if the provided `limit` value is `<=0`
* @throws InvalidArgumentError if the provided cursor is not a valid page token or `null`
*/
const curriedFn = async (
placeType: ContactTypeQualifier,
Expand Down Expand Up @@ -112,7 +113,7 @@ export namespace v1 {
* Returns a generator for fetching all places with the given type
* @param placeType the type of places to return
* @returns a generator for fetching all places with the given type
* @throws Error if no type is provided or if the type is not for a place
* @throws InvaidArgumentError if no type is provided or if the type is not for a place
*/
const curriedGen = (placeType: ContactTypeQualifier) => {
assertTypeQualifier(placeType);
Expand Down
8 changes: 4 additions & 4 deletions shared-libs/cht-datasource/src/report.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ export namespace v1 {
* returned. Subsequent pages can be retrieved by providing the cursor returned with the previous page.
* @param limit the maximum number of identifiers to return. Default is 10000.
* @returns a page of report identifiers for the provided specification
* @throws Error if no qualifier is provided or if the qualifier is invalid
* @throws Error if the provided `limit` value is `<=0`
* @throws Error if the provided cursor is not a valid page token or `null`
* @throws InvalidArgumentError if no qualifier is provided or if the qualifier is invalid
* @throws InvalidArgumentError if the provided `limit` value is `<=0`
* @throws InvalidArgumentError if the provided cursor is not a valid page token or `null`
*/
const curriedFn = async (
qualifier: FreetextQualifier,
Expand Down Expand Up @@ -106,7 +106,7 @@ export namespace v1 {
* Returns a generator for fetching all report identifiers that match the given qualifier
* @param qualifier the limiter defining which identifiers to return
* @returns a generator for fetching all report identifiers that match the given qualifier
* @throws Error if no qualifier is provided or if the qualifier is invalid
* @throws InvalidArgumentError if no qualifier is provided or if the qualifier is invalid
*/
const curriedGen = (
qualifier: FreetextQualifier
Expand Down

0 comments on commit 43efbef

Please sign in to comment.