@osdk/typescript-sdk-docs 0.26.0 → 0.26.1-main-86c708bd9cdef1d9a8d438a9fa0bc38f7d8116ea

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @osdk/typescript-sdk-docs
 
+## 0.26.1-main-86c708bd9cdef1d9a8d438a9fa0bc38f7d8116ea
+
+### Patch Changes
+
+- 86c708b: Recommend $select in object loading snippets and JSDoc, stop collecting asyncIter() into arrays in "load all objects" snippets, and document snapshot behavior of fetchPage vs asyncIter
+
 ## 0.26.0
 
 ### Minor Changes

package/build/browser/generatedNoCheck/docsNoComputedVariables.js

@@ -174,7 +174,7 @@ export const snippets = {
           "template": "import type { LoadObjectSetError, Page, Result } from \"{{{packageName}}}\";\nimport { {{objectType}} } from \"{{{packageName}}}/ontology/objects\";\n\nconst response: Result<Page<{{objectType}}>, LoadObjectSetError> = await client.ontology.objects.{{objectType}}\n    .fetchPageWithErrors({ pageSize: 30 });\n\n// To fetch a page without a result wrapper, use fetchPage instead\nconst responseNoErrorWrapper: Page<{{objectType}}> = await client.ontology.objects.{{objectType}}\n    .fetchPage({ pageSize: 30 });"
         }],
         "loadAllObjectsReference": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}/ontology/objects\";\n\nconst objects: {{objectType}}[]= [];\n\nfor await(const obj of client.ontology.objects.{{objectType}}.asyncIter()) {\n    objects.push(obj);\n}\nconst object = objects.value[0];"
+          "template": "import { {{objectType}} } from \"{{{packageName}}}/ontology/objects\";\n\n// asyncIter() loads every matching object, page after page. Handle each object as it arrives\n// rather than collecting them all into an array. For counts, sums, or group-bys, use an\n// aggregation instead; for a sample or the first N objects, use fetchPage({ pageSize }).\nfor await(const obj of client.ontology.objects.{{objectType}}.asyncIter()) {\n    console.log(obj.{{titleProperty}});\n}"
         }],
         "loadLinkedObjectReference": [{
           "template": "import type { GetLinkedObjectError, Result } from \"{{{packageName}}}\";\nimport { {{sourceObjectType}}, {{linkedObjectType}} } from \"{{{packageName}}}/ontology/objects\";\n\nfunction getLinked{{linkedObjectType}}(source: {{sourceObjectType}}, linkedObjectPrimaryKey: {{linkedPrimaryKeyPropertyV1.type}}): Result<{{linkedObjectType}}, GetLinkedObjectError>\n{\n    return source.{{linkApiName}}.fetchOneWithErrors(linkedObjectPrimaryKey);\n}\n\n// You can also get a linked object without the result wrapper\nfunction getLinkedNoWrapper{{linkedObjectType}}(source: {{sourceObjectType}}, linkedObjectPrimaryKey: {{linkedPrimaryKeyPropertyV1.type}}): {{linkedObjectType}} {\n    return source.{{linkApiName}}.fetchOne(linkedObjectPrimaryKey);\n}",
@@ -305,27 +305,27 @@ export const snippets = {
     "2.0.0": {
       "snippets": {
         "loadSingleObjectGuide": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk } from \"@osdk/client\";\n\ntry {\n    const object: Osdk.Instance<{{objectType}}> = await client({{objectType}}).fetchOne({{{primaryKeyPropertyValueV2}}});\n}\ncatch(e) {\n    throw e;\n}",
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk } from \"@osdk/client\";\n\n// $select only the properties you read; without it, the default property set is loaded.\ntry {\n    const object: Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\"> = await client({{objectType}})\n        .fetchOne({{{primaryKeyPropertyValueV2}}}, { $select: [\"{{titleProperty}}\"] });\n}\ncatch(e) {\n    throw e;\n}",
           "computedVariables": ["primaryKeyPropertyValueV2"]
         }],
         "loadObjectPageGuide": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\ntry {\n    const firstPage: PageResult<Osdk.Instance<{{objectType}}>>\n        = await client({{objectType}}).fetchPage({ $pageSize: 30 });\n    if (firstPage.nextPageToken === undefined) {\n        console.log(firstPage.data);\n    }\n    const secondPage: PageResult<Osdk.Instance<{{objectType}}>>\n    = await client({{objectType}}).fetchPage({ $pageSize: 30, $nextPageToken: firstPage.nextPageToken });\n    console.log([...firstPage.data, ...secondPage.data]);\n}\ncatch (e) {\n    throw e;\n}"
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\n// $select only the properties you read. Without it, the API loads its default property set,\n// and reading fewer properties afterwards does not avoid the cost of fetching them.\n// $pageSize is the size of one page, not a limit on the total number of objects.\n// fetchPage does not request a snapshot unless you pass $snapshot: true (a snapshot configured for\n// a function run still applies). Without one, if data changes between requests, later pages may\n// repeat or skip objects. Pass $snapshot: true on every request to page through one consistent\n// view, or use asyncIter(), which always requests a snapshot.\ntry {\n    const firstPage: PageResult<Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\">>\n        = await client({{objectType}}).fetchPage({ $select: [\"{{titleProperty}}\"], $pageSize: 30 });\n    if (firstPage.nextPageToken === undefined) {\n        console.log(firstPage.data);\n    }\n    const secondPage: PageResult<Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\">>\n        = await client({{objectType}}).fetchPage({\n            $select: [\"{{titleProperty}}\"],\n            $pageSize: 30,\n            $nextPageToken: firstPage.nextPageToken,\n        });\n    console.log([...firstPage.data, ...secondPage.data]);\n}\ncatch (e) {\n    throw e;\n}"
         }],
         "orderObjectsGuide": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\ntry {\n    const page: PageResult<Osdk.Instance<{{objectType}}>> = await client({{objectType}})\n        .fetchPage({\n            $orderBy: {\"{{titleProperty}}\": \"asc\"},\n            $pageSize: 30\n        });\n    const objects = page.data;\n    const object = objects[0];\n} catch (e) {\n    throw e;\n}"
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\n// $select only the properties you read; without it, the default property set is loaded.\n// $pageSize is the size of one page, not a limit on the total number of objects.\ntry {\n    const page: PageResult<Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\">> = await client({{objectType}})\n        .fetchPage({\n            $select: [\"{{titleProperty}}\"],\n            $orderBy: {\"{{titleProperty}}\": \"asc\"},\n            $pageSize: 30\n        });\n    const objects = page.data;\n    const object = objects[0];\n} catch (e) {\n    throw e;\n}"
         }],
         "searchObjectsGuide": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\ntry {\n    const page: PageResult<Osdk.Instance<{{objectType}}>> = await client({{objectType}})\n        .where({\n            {{titleProperty}}: {$isNull: true}\n        })\n        .fetchPage({\n            $pageSize: 30\n        });\n    const objects = page.data;\n    const object = objects[0];\n} catch (e) {\n    throw e;\n}"
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\n// $select only the properties you read; without it, the default property set is loaded.\n// $pageSize is the size of one page, not a limit on the total number of objects.\ntry {\n    const page: PageResult<Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\">> = await client({{objectType}})\n        .where({\n            {{titleProperty}}: {$isNull: true}\n        })\n        .fetchPage({\n            $select: [\"{{titleProperty}}\"],\n            $pageSize: 30\n        });\n    const objects = page.data;\n    const object = objects[0];\n} catch (e) {\n    throw e;\n}"
         }],
         "loadSingleObjectReference": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport type { Osdk } from \"@osdk/client\";\n\nconst responseNoErrorWrapper: Osdk.Instance<{{objectType}}> = await client({{objectType}}).fetchOne({{{primaryKeyPropertyValueV2}}});\n\n// Ontology-defined derived properties are not returned by default.\n// Pass their API names in $select, along with any other properties you need.\n// Runtime-defined derived properties added via .withProperties(...) are returned\n// by default only when $select is omitted. If you pass $select, include them\n// in the selection as well.\nfunction getWithSelectedProperties(properties: {{objectType}}.PropertyKeys[]) {\n    return client({{objectType}}).fetchOne({{{primaryKeyPropertyValueV2}}}, {\n        $select: properties\n    });\n}\n\n",
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport type { Osdk } from \"@osdk/client\";\n\n// $select only the properties you read; without it, the default property set is loaded.\nconst responseNoErrorWrapper: Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\"> = await client({{objectType}})\n    .fetchOne({{{primaryKeyPropertyValueV2}}}, { $select: [\"{{titleProperty}}\"] });\n\n// Ontology-defined derived properties are not returned by default.\n// Pass their API names in $select, along with any other properties you need.\n// Runtime-defined derived properties added via .withProperties(...) are returned\n// by default only when $select is omitted. If you pass $select, include them\n// in the selection as well.\nfunction getWithSelectedProperties(properties: {{objectType}}.PropertyKeys[]) {\n    return client({{objectType}}).fetchOne({{{primaryKeyPropertyValueV2}}}, {\n        $select: properties\n    });\n}\n\n",
           "computedVariables": ["primaryKeyPropertyValueV2"]
         }],
         "loadObjectsReference": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport type { Osdk, PageResult } from \"@osdk/client\";\ntry {\n    const responseNoErrorWrapper: PageResult<Osdk.Instance<{{objectType}}>>\n        = await client({{objectType}}).fetchPage({ $pageSize: 30 });\n} catch (e) {\n    throw e;\n}\n\n// Ontology-defined derived properties are not returned by default.\n// Pass their API names in $select, along with any other properties you need.\n// Runtime-defined derived properties added via .withProperties(...) are returned\n// by default only when $select is omitted. If you pass $select, include them\n// in the selection as well.\nfunction getPageWithSelectedProperties(properties: {{objectType}}.PropertyKeys[]) {\n    return client({{objectType}}).fetchPage({\n        $pageSize: 30,\n        $select: properties\n    });\n}\n"
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport type { Osdk, PageResult } from \"@osdk/client\";\n// $select only the properties you read; without it, the default property set is loaded.\n// $pageSize is the size of one page. Continue with page.nextPageToken to load more.\ntry {\n    const responseNoErrorWrapper: PageResult<Osdk.Instance<{{objectType}}, never, \"{{titleProperty}}\">>\n        = await client({{objectType}}).fetchPage({ $select: [\"{{titleProperty}}\"], $pageSize: 30 });\n} catch (e) {\n    throw e;\n}\n\n// Ontology-defined derived properties are not returned by default.\n// Pass their API names in $select, along with any other properties you need.\n// Runtime-defined derived properties added via .withProperties(...) are returned\n// by default only when $select is omitted. If you pass $select, include them\n// in the selection as well.\nfunction getPageWithSelectedProperties(properties: {{objectType}}.PropertyKeys[]) {\n    return client({{objectType}}).fetchPage({\n        $pageSize: 30,\n        $select: properties\n    });\n}\n"
         }],
         "loadAllObjectsReference": [{
-          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport type { Osdk } from \"@osdk/client\";\n\nasync function getAll(): Promise<Array<Osdk.Instance<{{objectType}}>>> {\n    const objects: Osdk.Instance<{{objectType}}>[]= [];\n    for await(const obj of client({{objectType}}).asyncIter()) {\n        objects.push(obj);\n    }\n\n    return objects;\n}\n\n// If Array.fromAsync() is available in your target environment\nfunction getAllFromAsync(): Promise<Array<Osdk.Instance<{{objectType}}>>> {\n    return Array.fromAsync(client({{objectType}}).asyncIter());\n}\n\n// Ontology-defined derived properties are not returned by default.\n// Pass their API names in $select, along with any other properties you need.\n// Runtime-defined derived properties added via .withProperties(...) are returned\n// by default only when $select is omitted. If you pass $select, include them\n// in the selection as well.\nasync function getAllWithSelectedProperties(properties: {{objectType}}.PropertyKeys[]) {\n    const objects = [];\n    for await (const obj of client({{objectType}}).asyncIter({ $select: properties })) {\n        objects.push(obj);\n    }\n    return objects;\n}"
+          "template": "import { {{objectType}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\n\n// Before loading every object, check whether you need to:\n// - Count, sum, or group objects: use .aggregate() instead, which never loads the objects.\n// - Show a sample or the first N objects: use fetchPage({ $pageSize }) instead.\n//\n// asyncIter() fetches page after page until every matching object has been loaded:\n// - $select only the properties you read. Without it, the API loads its default property set,\n//   and reading fewer properties afterwards does not avoid the cost of fetching them. Loading\n//   unused properties wastes bandwidth and compute and can slow down retrieval.\n// - Handle each object as it arrives rather than collecting them all into an array, so that\n//   memory use does not grow with the size of the object set.\n// - asyncIter() requests a consistent snapshot. For non-stream-backed object types, a completed\n//   traversal returns each object exactly once even if the data changes. If the snapshot expires\n//   or the backend detects a paging inconsistency (PagingInconsistencyDetected), it throws.\n//   Stream-backed object types do not provide this guarantee across pages: changes during the\n//   traversal can cause it to throw, and exactly-once traversal is not guaranteed.\n//   If a traversal fails this way, $select fewer properties and narrow the object set with a\n//   filter so it finishes sooner, or page with fetchPage() yourself, which does not request a\n//   snapshot by default but may then return duplicate or missing objects if the data changes.\nfor await (const obj of client({{objectType}}).asyncIter({ $select: [\"{{titleProperty}}\"] })) {\n    console.log(obj.{{titleProperty}});\n}\n\n// Ontology-defined derived properties are not returned by default.\n// Pass their API names in $select, along with any other properties you need.\n// Runtime-defined derived properties added via .withProperties(...) are returned\n// by default only when $select is omitted. If you pass $select, include them\n// in the selection as well.\nasync function logAllWithSelectedProperties(properties: {{objectType}}.PropertyKeys[]) {\n    for await (const obj of client({{objectType}}).asyncIter({ $select: properties })) {\n        console.log(obj);\n    }\n}"
         }],
         "loadLinkedObjectReference": [{
           "template": "import { type {{objectType}} } from \"{{{packageName}}}\";\nimport { type Osdk } from \"@osdk/client\";\n\nasync function getLinked{{linkedObjectType}}(source: Osdk.Instance<{{objectType}}>) {\n    try {\n        {{#isLinkManySided}}\n        return await source.$link.{{linkApiName}}.fetchPage();\n        {{/isLinkManySided}}\n        {{^isLinkManySided}}\n        return await source.$link.{{linkApiName}}.fetchOne();\n        {{/isLinkManySided}}\n    } catch (error) {\n        return { error };\n    }\n}"
@@ -442,7 +442,7 @@ export const snippets = {
           "template": "import { {{interfaceApiName}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\nconst response:  PageResult<Osdk<{{interfaceApiName}}>>\n    = await client({{interfaceApiName}}).fetchPage({ $pageSize: 30 });"
         }],
         "loadAllInterfacesReference": [{
-          "template": "import { {{interfaceApiName}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport type { Osdk } from \"@osdk/client\";\n\nconst interfaces: Osdk<{{interfaceApiName}}>[] = [];\n\nfor await(const int of client({{interfaceApiName}}).asyncIter()) {\n    interfaces.push(int);\n}\nconst interface1 = interfaces[0];"
+          "template": "import { {{interfaceApiName}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\n\n// asyncIter() fetches page after page until every matching object has been loaded:\n// - Pass $select: [...] with only the properties you read. Without it, the API loads its\n//   default property set.\n// - Handle each object as it arrives rather than collecting them all into an array.\n// - It requests a consistent snapshot, so for non-stream-backed object types a completed traversal\n//   returns each object exactly once. It throws if the snapshot expires or the backend detects a\n//   paging inconsistency. Stream-backed object types do not provide this guarantee across pages.\n//   If it fails, select fewer properties, narrow with a filter, or page with fetchPage().\n// - For counts, sums, or group-bys, use .aggregate() instead; for a sample or the first N\n//   objects, use fetchPage({ $pageSize }).\nfor await (const int of client({{interfaceApiName}}).asyncIter()) {\n    console.log(int.$primaryKey);\n}"
         }],
         "loadOrderedInterfacesReference": [{
           "template": "import { {{interfaceApiName}} } from \"{{{packageName}}}\";\n// Edit this import if your client location differs\nimport { client } from \"./client\";\nimport { type Osdk, type PageResult } from \"@osdk/client\";\n\ntry {\n    const page: PageResult<Osdk<{{interfaceApiName}}>> = await client({{interfaceApiName}})\n        .fetchPage({\n            $orderBy: { {{property}}: \"asc\"},\n            $pageSize: 30\n        });\n} catch (e) {\n    throw e;\n}"