TypeScript Client for Unbody's GraphQL API

[amirhouieh]

Description:

We require the development of a TypeScript client that interfaces with Unbody's GraphQL API. This client will strictly serve as a read-only interface, meaning no mutations are to be performed. It's important to note that Unbody utilizes Weaviate as its primary database. Consequently, all the operators, filters, and other functionalities will be consistent with those provided by Weaviate.

Objectives:

1. Create a seamless client that allows developers to easily interact with Unbody's API, focusing on retrieval operations.
2. Ensure compatibility and functionality mirroring Weaviate's operators and filters.
3. Prioritize developer experience, promoting intuitive method chaining and clear query structure.

Potential Approaches:

1. Apollo Client Integration:

• Leverage the Apollo Client as a foundational layer.
• Enhance this integration with generative type definitions, providing better type safety and auto-completion features.

• Example Usage:

   import { ApolloClient, InMemoryCache, gql } from '@apollo/client';
  
   const client = new ApolloClient({
     uri: 'YOUR_UNBODY_GRAPHQL_ENDPOINT',
     cache: new InMemoryCache(),
     headers: {
       'x-api-key': 'YOUR_UNBODY_API_KEY'
     }
   });
  
   const GET_GDOC = gql`
     query GetGdoc($title: String!) {
       gdoc(where: { title: { _eq: $title } }) {
         title
       }
     }
   `;
  
   client.query({
     query: GET_GDOC,
     variables: {
       title: "Bitcoin"
     }
   }).then(data => console.log(data));

2. Custom Client Development (Current Proposal):

• Design and implement our own custom client tailored for optimal developer experience.

• Aim for a usage pattern that allows developers to send requests to Unbody API in an intuitive manner. For instance:

   const client = new Unbody(UNBODY_API_KEY, UNBODY_LPE_PROJECT_ID);
  
   const res = await client.get.gdoc
     .where(
       WhereArgs.OR([
         WhereArgs.EQUAL(["title"], "Bitcoin"),
         WhereArgs.LIKE(["title"], "Ethereum"),
       ])
     )
     .nearText(NearTextArgsClass.concepts("cryptocurrency"))
     .select('title')
     .exec();

3. A combination of both?

While leveraging the powerful functionalities such as caching mechanism and local variables provided by Apollo, we can still design our own class base interface like approach 2.

Feedback and Collaboration:

We welcome contributions, ideas, and feedback from the community. If you have expertise or suggestions regarding these approaches or envision another potential solution, please share.

[miladazhdehnia]

Description:

This proposal aims to create a more readable and reusable syntax based on my experience as a full-stack developer. If you're interested, we can discuss these approaches further.

Approaches:

1. These approaches are more like an ORM/ODM, and we can have both at same time.

I think this more readable in terms of nested where, orWhere and other query operators.

const response = await unbody.gdoc.find({
    where: {
        title: 'Bitcoin' /* default behaviour = equals */,
        orWhere: {
            title: {like: 'Ethereum'}
        }
    },
    nearText: ['cryptocurrency'],
    select: ['title'], /* and { exclude: ['id'] }, this way we can get every field except excluded */
    /* limit, pagination and other options */
})

This is more favorable for chain lovers :D.

const response = await unbody.gdoc
    .find()
    .where({title: 'Bitcoin'})
    .orWhere({title: {like: 'Ethereum'}})
    .nearText(['cryptocurrency'])
    .select(['title'])
    .exec()

3. This approach should be designed to function like an SDK.

   
   // We can reuse gdoc object
   const gdocListEntity = unbody.gdoc({fields: ['title'] /* and { exclude: ['id'] }, this way we can get every field except excluded */, /* limit, pagination and other options */})

const cryptoDocs = gdocListEntity .title('Bitcoin', 'Tron') .html('

text

') .alternate() // syntax sugar for or operator .title({like: 'Ethereum'})

const fiatDocs = gdocListEntity .title('United states dollar') .html('

USD

') .alternate() // syntax sugar for or operator .title({like: 'USD'}) .get() // Replacement for exec

const gdocSingleEntity = unbody.gdoc({ fields: ['title', 'html'] / and { exclude: ['id'] }, this way we can get every field except excluded /, limit: 1 / limit, pagination and other options /, }) const fiatDocs = gdocSingleEntity .id('XXXXXX') .get() // Replacement for exec

[amirhouieh]

@miladazhdehnia Thanks for the proposal. I see we both see potential in Approach 2, and we think it's the best way forward.

A couple of things I'm wondering about:

• With TypeScript playing a big role, how do you envision us handling type definitions? Are we leaning towards generative or more hardcoded?
• Regarding Apollo, are you thinking of integrating it? It's got some features, especially caching, that seem interesting.

Keen to hear your thoughts 🤔

[miladazhdehnia]

As we've decided to move forward with the second proposed approach, the implementation will kick off from here