feat: Support entity type mappings (#206)

* feat: introduced basic type map

For later extensibility.

* feat: use stronger types

* fix: tests pass

* fix: compile issues

* fix: better `ensure` types

* fix: keyof everywhere

* Update source/types.ts

Co-authored-by: Lars Johansson <[email protected]>

* Refinements

* K to TEntityType

* Make the entitytype key the base for the responses as well

* Review Fixes

* TS/Prettier/Import fixes

* Made EntityType generic naming consistent

* WIP

* send tentitytypemap as a generic

* add documentation

---------

Co-authored-by: Mathias Lorenzen <[email protected]>
Co-authored-by: Mathias Lykkegaard Lorenzen <[email protected]>
Co-authored-by: Lars Johansson <[email protected]>
Co-authored-by: Lars Johansson <[email protected]>

Author: 3 people

README.md

@@ -34,6 +34,23 @@ yarn:
 yarn add @ftrack/api
 ```
 
+## TypeScript: Generated Schema Types
+
+You can generate schema types for your own workspace with [@ftrack/ts-schema-generator](https://github.com/ftrackhq/ftrack-ts-schema-generator).
+
+Once generated, you can integrate them with @ftrack/api by passing them as a type variable:
+
+```ts
+import SchemaTypes from "./__generated__/schema.ts"
+import { Session } from @ftrack/api
+
+const session = new Session<SchemaTypes>(...);
+
+// user will now be of type User
+// and provide all available properties for its entity type.
+const user = await session.query<"User">("...");
+```
+
 ## Tutorial
 
 The API uses sessions to manage communication with an ftrack server. Create a session that connects to your ftrack server (changing the passed values as appropriate):

source/operation.ts

@@ -4,9 +4,9 @@
  * @namespace operation
  */
 
-export interface CreateOperation {
+export interface CreateOperation<TEntityType> {
   action: "create";
-  entity_type: string;
+  entity_type: TEntityType;
   entity_data: any;
 }
 
@@ -15,33 +15,33 @@ export interface QueryOperation {
   expression: string;
 }
 
-export interface SearchOperationOptions {
+export interface SearchOperationOptions<TEntityType> {
   expression?: string;
-  entityType?: string;
+  entityType?: TEntityType;
   terms?: string[];
   contextId?: string;
   objectTypeIds?: string[];
 }
 
-export interface SearchOperation {
+export interface SearchOperation<TEntityType> {
   action: "search";
   expression?: string;
-  entity_type?: string;
+  entity_type?: TEntityType;
   terms?: string[];
   context_id?: string;
   object_type_ids?: string[];
 }
 
-export interface UpdateOperation {
+export interface UpdateOperation<TEntityType> {
   action: "update";
-  entity_type: string;
+  entity_type: TEntityType;
   entity_key: string[] | string;
   entity_data: any;
 }
 
-export interface DeleteOperation {
+export interface DeleteOperation<TEntityType> {
   action: "delete";
-  entity_type: string;
+  entity_type: TEntityType;
   entity_key: string[] | string;
 }
 
@@ -61,12 +61,12 @@ export interface GetUploadMetadataOperation {
   component_id: string;
 }
 
-export type Operation =
-  | CreateOperation
+export type Operation<TEntityType> =
+  | CreateOperation<TEntityType>
   | QueryOperation
-  | SearchOperation
-  | UpdateOperation
-  | DeleteOperation
+  | SearchOperation<TEntityType>
+  | UpdateOperation<TEntityType>
+  | DeleteOperation<TEntityType>
   | QueryServerInformationOperation
   | QuerySchemasOperation
   | GetUploadMetadataOperation
@@ -81,7 +81,10 @@ export type Operation =
  * @param  {Object} data Entity data to use for creation
  * @return {Object}      API operation
  */
-export function create(type: string, data: any): CreateOperation {
+export function create<TEntityType>(
+  type: TEntityType,
+  data: any,
+): CreateOperation<TEntityType> {
   return {
     action: "create",
     entity_type: type,
@@ -109,13 +112,13 @@ export function query(expression: string): QueryOperation {
  * @param  {string} expression API query expression
  * @return {Object}            API operation
  */
-export function search({
+export function search<TEntityType>({
   expression,
   entityType,
   terms,
   contextId,
   objectTypeIds,
-}: SearchOperationOptions): SearchOperation {
+}: SearchOperationOptions<TEntityType>): SearchOperation<TEntityType> {
   return {
     action: "search",
     expression,
@@ -136,11 +139,11 @@ export function search({
  * @param  {Object} data values to update
  * @return {Object}      API operation
  */
-export function update(
-  type: string,
+export function update<TEntityType>(
+  type: TEntityType,
   keys: string[] | string,
   data: any,
-): UpdateOperation {
+): UpdateOperation<TEntityType> {
   return {
     action: "update",
     entity_type: type,
@@ -158,10 +161,10 @@ export function update(
  * @param  {Array} keys Identifying keys, typically [<entity id>]
  * @return {Object}      API operation
  */
-function deleteOperation(
-  type: string,
+function deleteOperation<TEntityType>(
+  type: TEntityType,
   keys: string[] | string,
-): DeleteOperation {
+): DeleteOperation<TEntityType> {
   return {
     action: "delete",
     entity_type: type,

source/project_schema.ts

@@ -2,7 +2,7 @@
 
 import * as operation from "./operation.js";
 import { Session } from "./session.js";
-import type { Data, QueryResponse } from "./types.js";
+import type { QueryResponse } from "./types.js";
 /**
  * Project schema namespace
  * @namespace project_schema
@@ -18,8 +18,8 @@ import type { Data, QueryResponse } from "./types.js";
  *
  * @memberof project_schema
  */
-export function getStatuses(
-  session: Session,
+export function getStatuses<TEntityTypeMap extends Record<string, any>>(
+  session: Session<TEntityTypeMap>,
   projectSchemaId: string,
   entityType: string,
   typeId: string | null = null,
@@ -71,7 +71,8 @@ export function getStatuses(
     ),
   );
 
-  response = session.call<QueryResponse<Data>>(operations);
+  response =
+    session.call<QueryResponse<TEntityTypeMap["ProjectSchema"]>>(operations);
   response = response.then((results) => {
     // Since the operations where performed in one batched call,
     // the result will be merged into a single entity.