JS Docs

.changeset/clever-rings-yawn.md

@@ -0,0 +1,6 @@
+---
+"@osdk/client.api": patch
+"@osdk/client": patch
+---
+
+Add docs for object sets and attachments.

etc/client.api.report.api.md

@@ -127,9 +127,7 @@ export type ApplyBatchActionOptions = {
 
 // @public (undocumented)
 export interface Attachment {
-    // (undocumented)
     fetchContents(): Promise<Blob>;
-    // (undocumented)
     fetchMetadata(): Promise<AttachmentMetadata>;
     // (undocumented)
     rid: string;
@@ -397,7 +395,7 @@ export interface InterfaceObjectSet<Q extends InterfaceDefinition<any, any>> ext
 
 // Warning: (ae-forgotten-export) The symbol "OkResult" needs to be exported by the entry point index.d.ts
 //
-// @public (undocumented)
+// @public
 export function isOk<X>(a: Result<X>): a is OkResult<X>;
 
 // @public (undocumented)
@@ -408,13 +406,23 @@ export type LinkNames<Q extends ObjectOrInterfaceDefinition> = keyof Q["links"]
 
 // @public (undocumented)
 export interface MinimalObjectSet<Q extends ObjectOrInterfaceDefinition> extends BaseObjectSet<Q> {
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     asyncIter: () => AsyncIterableIterator<Osdk<Q, "$all">>;
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     fetchPage: <L extends ObjectOrInterfacePropertyKeysFrom2<Q>, R extends boolean, const A extends Augments, S extends NullabilityAdherence = NullabilityAdherenceDefault>(args?: FetchPageArgs<Q, L, R, A, S>) => Promise<FetchPageResult<Q, L, R, S>>;
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     fetchPageWithErrors: <L extends ObjectOrInterfacePropertyKeysFrom2<Q>, R extends boolean, const A extends Augments, S extends NullabilityAdherence = NullabilityAdherenceDefault>(args?: FetchPageArgs<Q, L, R, A, S>) => Promise<Result<FetchPageResult<Q, L, R, S>>>;
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     where: (clause: WhereClause<Q>) => MinimalObjectSet<Q>;
 }
 
@@ -440,21 +448,27 @@ export type NumericAggregateOption = "min" | "max" | "sum" | "avg" | "approximat
 
 // @public (undocumented)
 export interface ObjectSet<Q extends ObjectOrInterfaceDefinition> extends MinimalObjectSet<Q> {
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     aggregate: <AO extends AggregateOpts<Q>>(req: AggregateOptsThatErrorsAndDisallowsOrderingWithMultipleGroupBy<Q, AO>) => Promise<AggregationsResults<Q, AO>>;
-    // (undocumented)
     fetchOne: Q extends ObjectTypeDefinition<any> ? <L extends ObjectOrInterfacePropertyKeysFrom2<Q>, R extends boolean, S extends false | "throw" = NullabilityAdherenceDefault>(primaryKey: PropertyValueClientToWire[Q["primaryKeyType"]], options?: SelectArg<Q, L, R, S>) => Promise<SingleOsdkResult<Q, L, R, S>> : never;
-    // (undocumented)
     fetchOneWithErrors: Q extends ObjectTypeDefinition<any> ? <L extends ObjectOrInterfacePropertyKeysFrom2<Q>, R extends boolean, S extends false | "throw" = NullabilityAdherenceDefault>(primaryKey: PropertyValueClientToWire[Q["primaryKeyType"]], options?: SelectArg<Q, L, R, S>) => Promise<Result<SingleOsdkResult<Q, L, R, S>>> : never;
-    // (undocumented)
     intersect: (...objectSets: ReadonlyArray<ObjectSet<Q>>) => ObjectSet<Q>;
-    // (undocumented)
     pivotTo: <L extends LinkNames<Q>>(type: L) => ObjectSet<LinkedType<Q, L>>;
-    // (undocumented)
     subtract: (...objectSets: ReadonlyArray<ObjectSet<Q>>) => ObjectSet<Q>;
-    // (undocumented)
     union: (...objectSets: ReadonlyArray<ObjectSet<Q>>) => ObjectSet<Q>;
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     where: (clause: WhereClause<Q>) => ObjectSet<Q>;
 }
 
@@ -712,13 +726,15 @@ export interface TimeSeriesPoint<T extends string | number> {
 
 // @public (undocumented)
 export interface TimeSeriesProperty<T extends number | string> {
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     asyncIterPoints(query?: TimeSeriesQuery): AsyncGenerator<TimeSeriesPoint<T>>;
-    // (undocumented)
+    // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
+    // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     getAllPoints(query?: TimeSeriesQuery): Promise<Array<TimeSeriesPoint<T>>>;
-    // (undocumented)
     getFirstPoint(): Promise<TimeSeriesPoint<T>>;
-    // (undocumented)
     getLastPoint(): Promise<TimeSeriesPoint<T>>;
 }
 

etc/client.report.api.md

@@ -75,7 +75,7 @@ export interface Client extends SharedClient<MinimalClient> {
     <Q extends QueryDefinition<any, any>>(o: CheckVersionBound<Q>): QuerySignatureFromDef<Q>;
 }
 
-// @public (undocumented)
+// @public
 export function createAttachmentFromRid(client: MinimalClient, rid: string): Attachment;
 
 // @public (undocumented)

packages/client.api/src/object/Attachment.ts

@@ -16,7 +16,13 @@
 
 export interface Attachment {
   rid: string;
+  /**
+   * Fetches metadata for an attachment
+   */
   fetchMetadata(): Promise<AttachmentMetadata>;
+  /**
+   * Fetches actual content of attachment in Blob form
+   */
   fetchContents(): Promise<Blob>;
 }
 /**

packages/client.api/src/object/Result.ts

@@ -18,10 +18,20 @@ export type ErrorResult = { error: Error; value?: never };
 export type OkResult<V> = { value: V; error?: never };
 export type Result<V> = OkResult<V> | ErrorResult;
 
+/**
+ * Check if a result was successfully received
+ * @param a - result wrapped value
+ * @returns whether a result has a value in it
+ */
 export function isOk<X>(a: Result<X>): a is OkResult<X> {
   return ("value" in a);
 }
 
+/**
+ * Check if a result contains an error value
+ * @param a Result wrapped value
+ * @returns whether a result has an error in it
+ */
 export function isError<X>(a: Result<X>): a is ErrorResult {
   return ("error" in a);
 }

packages/client.api/src/objectSet/ObjectSet.ts

@@ -44,6 +44,18 @@ import type { BaseObjectSet } from "./BaseObjectSet.js";
 export interface MinimalObjectSet<Q extends ObjectOrInterfaceDefinition>
   extends BaseObjectSet<Q>
 {
+  /**
+   * Gets a page of objects of this type, with a result wrapper
+   * @param args - Args to specify next page token and page size, if applicable
+   * @example
+   *  const myObjs = await objectSet.fetchPage({
+      $pageSize: 10,
+      $nextPageToken: "nextPage"
+    });
+     const myObjsResult = myObjs.data;
+
+   * @returns a page of objects
+   */
   fetchPage: <
     L extends ObjectOrInterfacePropertyKeysFrom2<Q>,
     R extends boolean,
@@ -53,6 +65,20 @@ export interface MinimalObjectSet<Q extends ObjectOrInterfaceDefinition>
     args?: FetchPageArgs<Q, L, R, A, S>,
   ) => Promise<FetchPageResult<Q, L, R, S>>;
 
+  /**
+   * Gets a page of objects of this type, with a result wrapper
+   * @param args - Args to specify next page token and page size, if applicable
+   * @example
+   *  const myObjs = await objectSet.fetchPage({
+      $pageSize: 10,
+      $nextPageToken: "nextPage"
+    });
+
+     if(isOk(myObjs)){
+     const myObjsResult = myObjs.value.data;
+    }
+   * @returns a page of objects, wrapped in a result wrapper
+   */
   fetchPageWithErrors: <
     L extends ObjectOrInterfacePropertyKeysFrom2<Q>,
     R extends boolean,
@@ -62,10 +88,28 @@ export interface MinimalObjectSet<Q extends ObjectOrInterfaceDefinition>
     args?: FetchPageArgs<Q, L, R, A, S>,
   ) => Promise<Result<FetchPageResult<Q, L, R, S>>>;
 
+  /**
+   * Allows you to filter an object set with a given clause
+   * @param clause - Takes a filter clause
+   * @example
+   * await client(Office).where({
+      meetingRooms: { $contains: "Grand Central" },
+      meetingRoomCapacities: { $contains: 30 },
+  });
+   * @returns an objectSet
+   */
   where: (
     clause: WhereClause<Q>,
   ) => MinimalObjectSet<Q>;
 
+  /**
+   * Returns an async iterator to load all objects of this type
+   * @example
+   * for await (const obj of myObjectSet.asyncIter()){
+   * // Handle obj
+   * }
+   * @returns an async iterator to load all objects
+   */
   asyncIter: () => AsyncIterableIterator<Osdk<Q, "$all">>;
 }
 
@@ -77,28 +121,96 @@ export interface InterfaceObjectSet<Q extends InterfaceDefinition<any, any>>
 export interface ObjectSet<Q extends ObjectOrInterfaceDefinition>
   extends MinimalObjectSet<Q>
 {
+  /**
+   * Aggregate on a field in an object type
+   * @param req - an aggregation request where you can select fields and choose how to aggregate, e.g., max, min, avg, and also choose
+   * whether or not you order your results. You can also specify a groupBy field to group your aggregations
+   * @example
+   * const testAggregateCountWithGroups = await client(BoundariesUsState)
+    .aggregate({
+      $select: {
+        $count: "unordered",
+        "latitude:max": "unordered",
+        "latitude:min": "unordered",
+        "latitude:avg": "unordered",
+      },
+      $groupBy: {
+        usState: "exact",
+        longitude: {
+          $fixedWidth: 10,
+        },
+      },
+    });
+
+   * @returns aggregation results, sorted in the groups based on the groupBy clause (if applicable)
+   */
   aggregate: <AO extends AggregateOpts<Q>>(
     req: AggregateOptsThatErrorsAndDisallowsOrderingWithMultipleGroupBy<Q, AO>,
   ) => Promise<AggregationsResults<Q, AO>>;
 
+  /**
+   * Allows you to filter an object set with a given clause
+   * @param clause - Takes a filter clause
+   * @example
+   * await client(Office).where({
+      meetingRooms: { $contains: "Grand Central" },
+      meetingRoomCapacities: { $contains: 30 },
+  });
+   * @returns an objectSet
+   */
   where: (
     clause: WhereClause<Q>,
   ) => ObjectSet<Q>;
 
+  /**
+   * Unions object sets together
+   * @param objectSets - objectSets you want to union with
+   * @example
+   * const unionObjectSet = complexFilteredEmployeeObjectSet.union(
+    simpleFilteredEmployeeObjectSet,
+  );
+   * @returns the unioned object set
+   */
   union: (
     ...objectSets: ReadonlyArray<ObjectSet<Q>>
   ) => ObjectSet<Q>;
 
+  /**
+   * Computes the intersection of object sets
+   * @param objectSets - objectSets you want to intersect with
+   * @example
+   * const intersectedObjectSet = complexFilteredEmployeeObjectSet.intersect(
+    simpleFilteredEmployeeObjectSet,
+  );
+   * @returns the intersected object set
+   */
   intersect: (
     ...objectSets: ReadonlyArray<ObjectSet<Q>>
   ) => ObjectSet<Q>;
 
+  /**
+   * Computes the subtraction of object sets
+   * @param objectSets - objectSets you want to subtract from
+   * @example
+   * const subtractObjectSet = complexFilteredEmployeeObjectSet.subtract(
+    simpleFilteredEmployeeObjectSet,
+  );
+   * @returns the subtract object set
+   */
   subtract: (
     ...objectSets: ReadonlyArray<ObjectSet<Q>>
   ) => ObjectSet<Q>;
 
+  /**
+   * Pivots the object set over to all its linked objects of the specified type
+   * @param type - The linked object type you want to pivot to
+   * @returns an object set of the specified linked type
+   */
   pivotTo: <L extends LinkNames<Q>>(type: L) => ObjectSet<LinkedType<Q, L>>;
 
+  /**
+   * Fetches one object with the specified primary key, without a result wrapper
+   */
   fetchOne: Q extends ObjectTypeDefinition<any> ? <
       L extends ObjectOrInterfacePropertyKeysFrom2<Q>,
       R extends boolean,
@@ -109,6 +221,9 @@ export interface ObjectSet<Q extends ObjectOrInterfaceDefinition>
     ) => Promise<SingleOsdkResult<Q, L, R, S>>
     : never;
 
+  /**
+   * Fetches one object with the specified primary key, with a result wrapper
+   */
   fetchOneWithErrors: Q extends ObjectTypeDefinition<any> ? <
       L extends ObjectOrInterfacePropertyKeysFrom2<Q>,
       R extends boolean,

packages/client.api/src/timeseries/timeseries.ts

@@ -68,8 +68,36 @@ export interface TimeSeriesPoint<T extends string | number> {
 }
 
 export interface TimeSeriesProperty<T extends number | string> {
+  /**
+   * Queries the first point of the Timeseries
+   */
   getFirstPoint(): Promise<TimeSeriesPoint<T>>;
+  /**
+   * Queries the last point of the Timeseries
+   */
   getLastPoint(): Promise<TimeSeriesPoint<T>>;
+  /**
+   * Loads all points, within the given time range if that's provided
+   * @param query - a query representing either an absolute or relative range of time
+   * @example
+   *  const points = await employee.employeeStatus?.getAllPoints({
+      $after: 1,
+      $unit: "month",
+    });
+   */
   getAllPoints(query?: TimeSeriesQuery): Promise<Array<TimeSeriesPoint<T>>>;
+  /**
+   * Returns an async iterator to load all points
+   * within the given time range if that's provided
+   * @param query - a query representing either an absolute or relative range of time
+   * @example
+   *  const iterator = employee.employeeStatus?.asyncIter({
+      $after: 1,
+      $unit: "month",
+    });
+    for await (const point of iterator) {
+        // Handle time series point
+    }
+   */
   asyncIterPoints(query?: TimeSeriesQuery): AsyncGenerator<TimeSeriesPoint<T>>;
 }

packages/client/src/createAttachmentFromRid.ts

@@ -18,6 +18,12 @@ import type { Attachment } from "@osdk/client.api";
 import { Ontologies } from "@osdk/internal.foundry";
 import type { MinimalClient } from "./MinimalClientContext.js";
 
+/**
+ * Helper function to create an attachment type from a rid
+ * @param client - minimal client
+ * @param rid - rid of attachment in Foundry
+ * @returns
+ */
 export function createAttachmentFromRid(
   client: MinimalClient,
   rid: string,