diff --git a/.trunk/trunk.yaml b/.trunk/trunk.yaml index ac5c835c..f81eb464 100644 --- a/.trunk/trunk.yaml +++ b/.trunk/trunk.yaml @@ -37,6 +37,7 @@ lint: - linters: [ALL] paths: - styles + - snippets - linters: [checkov] paths: - mint.json diff --git a/getting-started-with-hyper-commerce.mdx b/getting-started-with-hyper-commerce.mdx index fcb887ea..324479bb 100644 --- a/getting-started-with-hyper-commerce.mdx +++ b/getting-started-with-hyper-commerce.mdx @@ -119,15 +119,15 @@ In the Hypermode console, you’ll see several key components of your project: - **[Functions](/modus):** These are serverless functions written in AssemblyScript (a TypeScript-like language) that are automatically exposed as GraphQL APIs. Once deployed, you can query these functions within your app. -- **[Collections](/modus/sdk/collections):** Hypermode offers built-in key-value - storage, known as collections, with support for vector embeddings. This allows - you to store and retrieve data efficiently, without requiring a database for - basic use cases. -- **[Models](/modus/sdk/models):** This section represents the AI models defined - for your project. These models handle tasks like embedding text into vectors - for search. Hypermode provides open source shared and dedicated model hosting - for rapid experimentation. You can also connect to your preferred large - language model, including OpenAI, Anthropic, and Gemini. +- **[Collections](/modus/sdk/assemblyscript/collections):** Hypermode offers + built-in key-value storage, known as collections, with support for vector + embeddings. This allows you to store and retrieve data efficiently, without + requiring a database for basic use cases. +- **[Models](/modus/sdk/assemblyscript/models):** This section represents the AI + models defined for your project. These models handle tasks like embedding text + into vectors for search. Hypermode provides open source shared and dedicated + model hosting for rapid experimentation. You can also connect to your + preferred large language model, including OpenAI, Anthropic, and Gemini. - **[Connections](/modus/app-manifest#connections):** You define all external connections, with the runtime denying all other egress for secure-by-default processing. diff --git a/introduction.mdx b/introduction.mdx index db8dd72a..e0cc3a64 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -4,8 +4,6 @@ description: "Build Intelligent APIs." mode: "wide" --- ---- - ## What is Hypermode? {/* */} Hypermode is a managed service that provides the workbench and infrastructure to diff --git a/mint.json b/mint.json index 5583dc61..1302b71d 100644 --- a/mint.json +++ b/mint.json @@ -43,6 +43,48 @@ "url": "modus" } ], + "redirects": [ + { + "source": "/modus/sdk/collections", + "destination": "/modus/sdk/assemblyscript/collections" + }, + { + "source": "/modus/sdk/console", + "destination": "/modus/sdk/assemblyscript/console" + }, + { + "source": "/modus/sdk/dgraph", + "destination": "/modus/sdk/assemblyscript/dgraph" + }, + { + "source": "/modus/sdk/graphql", + "destination": "/modus/sdk/assemblyscript/graphql" + }, + { + "source": "/modus/sdk/http", + "destination": "/modus/sdk/assemblyscript/http" + }, + { + "source": "/modus/sdk/localtime", + "destination": "/modus/sdk/assemblyscript/localtime" + }, + { + "source": "/modus/sdk/models", + "destination": "/modus/sdk/assemblyscript/models" + }, + { + "source": "/modus/sdk/mysql", + "destination": "/modus/sdk/assemblyscript/mysql" + }, + { + "source": "/modus/sdk/neo4j", + "destination": "/modus/sdk/assemblyscript/neo4j" + }, + { + "source": "/modus/sdk/postgresql", + "destination": "/modus/sdk/assemblyscript/postgresql" + } + ], "navigation": [ { "group": "Getting Started", @@ -96,16 +138,40 @@ "pages": ["modus/deepseek-model"] }, { - "group": "API Reference", + "group": "SDK Reference", "pages": [ - "modus/sdk/collections", - "modus/sdk/console", - "modus/sdk/dgraph", - "modus/sdk/graphql", - "modus/sdk/http", - "modus/sdk/neo4j", - "modus/sdk/models", - "modus/sdk/postgresql" + { + "group": "AssemblyScript SDK", + "pages": [ + "modus/sdk/assemblyscript/overview", + "modus/sdk/assemblyscript/collections", + "modus/sdk/assemblyscript/console", + "modus/sdk/assemblyscript/dgraph", + "modus/sdk/assemblyscript/graphql", + "modus/sdk/assemblyscript/http", + "modus/sdk/assemblyscript/localtime", + "modus/sdk/assemblyscript/models", + "modus/sdk/assemblyscript/mysql", + "modus/sdk/assemblyscript/neo4j", + "modus/sdk/assemblyscript/postgresql" + ] + }, + { + "group": "Go SDK", + "pages": [ + "modus/sdk/go/overview", + "modus/sdk/go/collections", + "modus/sdk/go/console", + "modus/sdk/go/dgraph", + "modus/sdk/go/graphql", + "modus/sdk/go/http", + "modus/sdk/go/localtime", + "modus/sdk/go/models", + "modus/sdk/go/mysql", + "modus/sdk/go/neo4j", + "modus/sdk/go/postgresql" + ] + } ] }, { diff --git a/modus/app-manifest.mdx b/modus/app-manifest.mdx index 42b34948..1796af61 100644 --- a/modus/app-manifest.mdx +++ b/modus/app-manifest.mdx @@ -109,9 +109,10 @@ connection types: | Type | Purpose | Function Classes | | :----------- | :------------------------------- | :-------------------------- | | `http` | Connect to an HTTP(S) web server | `http`, `graphql`, `models` | -| `postgresql` | Connect to a PostgreSQL database | `postgresql` | | `dgraph` | Connect to a Dgraph database | `dgraph` | +| `mysql` | Connect to a MySQL database | `mysql` | | `neo4j` | Connect to a Neo4j database | `neo4j` | +| `postgresql` | Connect to a PostgreSQL database | `postgresql` | **Don't include secrets directly in the manifest!** @@ -130,11 +131,12 @@ where they're securely stored until needed. ### HTTP connection This connection type supports the HTTP and HTTPS protocols to communicate with -external hosts. You can use the [HTTP APIs](/modus/sdk/http) in the Modus SDK to -interact with the host. +external hosts. You can use the [HTTP APIs](/modus/sdk/assemblyscript/http) in +the Modus SDK to interact with the host. -This connection type is also used for [GraphQL APIs](/modus/sdk/graphql) and to -invoke externally hosted AI [models](/modus/sdk/models). +This connection type is also used for +[GraphQL APIs](/modus/sdk/assemblyscript/graphql) and to invoke externally +hosted AI [models](/modus/sdk/assemblyscript/models). **Example:** @@ -246,94 +248,92 @@ This example specifies a query parameter named `key` provided by a secret named -### PostgreSQL connection +### Dgraph connection -This connection type supports connecting to PostgreSQL databases. You can use -the [PostgreSQL APIs](/modus/sdk/postgresql) in the Modus SDK to interact with -the database. +This connection type supports connecting to Dgraph databases. You can use the +[Dgraph APIs](/modus/sdk/assemblyscript/dgraph) in the Modus SDK to interact +with the database. **Example:** ```json modus.json { "connections": { - "my-database": { - "type": "postgresql", - "connString": "postgresql://{{PG_USER}}:{{PG_PASSWORD}}@db.example.com:5432/data?sslmode=require" + "my-dgraph": { + "type": "dgraph", + "grpcTarget": "frozen-mango.grpc.eu-central-1.aws.cloud.dgraph.io:443", + "key": "{{DGRAPH_API_KEY}}" } } } ``` - Always set to `"postgresql"` for this connection type. + Always set to `"dgraph"` for this connection type. - - The connection string for the PostgreSQL database. - -Values may include variables using the `{{VARIABLE}}` template syntax, which -resolve at runtime to secrets provided for each connection, via the Hypermode -Console. - -The connection string in the preceding example includes: - -- A username and password provided by secrets named `PG_USER` & `PG_PASSWORD` -- A host named `db.example.com` on port `5432` -- A database named `data` -- SSL mode set to `require` - which is highly recommended for secure connections - -Refer to -[the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) -for more details on connection strings. - - - -Managed PostgreSQL providers often provide a pre-made connection string for you -to copy. Check your provider's documentation for details. - -For example, if using Neon, refer to the -[Neon documentation](https://neon.tech/docs/connect/connect-from-any-app). - - + + The gRPC target for the Dgraph database. + + + The API key for the Dgraph database. -### Dgraph connection +### MySQL connection -This connection type supports connecting to Dgraph databases. You can use the -[Dgraph APIs](/modus/sdk/dgraph) in the Modus SDK to interact with the database. +This connection type supports connecting to MySQL databases. You can use the +[MySQL APIs](/modus/sdk/assemblyscript/mysql) in the Modus SDK to interact with +the database. **Example:** ```json modus.json { "connections": { - "my-dgraph": { - "type": "dgraph", - "grpcTarget": "frozen-mango.grpc.eu-central-1.aws.cloud.dgraph.io:443", - "key": "{{DGRAPH_API_KEY}}" + "my-database": { + "type": "mysql", + "connString": "mysql://{{USERNAME}}:{{PASSWORD}}@db.example.com:3306/dbname?tls=true" } } } ``` - Always set to `"dgraph"` for this connection type. + Always set to `"mysql"` for this connection type. - - The gRPC target for the Dgraph database. - + + The connection string for the MySQL database. + +Values may include variables using the `{{VARIABLE}}` template syntax, which +resolve at runtime to secrets provided for each connection, via the Hypermode +Console. + +The connection string in the preceding example includes: + +- A username and password provided by secrets named `USERNAME` & `PASSWORD` +- A host named `db.example.com` on port `3306` +- A database named `dbname` +- Encryption enabled via `tls=true` - which is highly recommended for secure + connections + +Set the connection string using a URI format +[as described in the MySQL documentation](https://dev.mysql.com/doc/refman/8.4/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri). + +However, any optional parameters provided should be in the form specified by the +Go MySQL driver used by the Modus Runtime, +[as described here](https://github.com/go-sql-driver/mysql/blob/master/README.md#parameters) + +For example, use `tls=true` to enable encryption (not `sslmode=require`). - - The API key for the Dgraph database. ### Neo4j connection This connection type supports connecting to Neo4j databases. You can use the -[Neo4j APIs](/modus/sdk/neo4j) in the Modus SDK to interact with the database. +[Neo4j APIs](/modus/sdk/assemblyscript/neo4j) in the Modus SDK to interact with +the database. **Example:** @@ -366,6 +366,59 @@ This connection type supports connecting to Neo4j databases. You can use the The password for the Neo4j database. +### PostgreSQL connection + +This connection type supports connecting to PostgreSQL databases. You can use +the [PostgreSQL APIs](/modus/sdk/assemblyscript/postgresql) in the Modus SDK to +interact with the database. + +**Example:** + +```json modus.json +{ + "connections": { + "my-database": { + "type": "postgresql", + "connString": "postgresql://{{PG_USER}}:{{PG_PASSWORD}}@db.example.com:5432/data?sslmode=require" + } + } +} +``` + + + Always set to `"postgresql"` for this connection type. + + + + The connection string for the PostgreSQL database. + +Values may include variables using the `{{VARIABLE}}` template syntax, which +resolve at runtime to secrets provided for each connection, via the Hypermode +Console. + +The connection string in the preceding example includes: + +- A username and password provided by secrets named `PG_USER` & `PG_PASSWORD` +- A host named `db.example.com` on port `5432` +- A database named `data` +- SSL mode set to `require` - which is highly recommended for secure connections + +Refer to +[the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) +for more details on connection strings. + + + +Managed PostgreSQL providers often provide a pre-made connection string for you +to copy. Check your provider's documentation for details. + +For example, if using Neon, refer to the +[Neon documentation](https://neon.tech/docs/connect/connect-from-any-app). + + + + + ### Working locally with secrets When you run your app locally using `modus dev`, the runtime replaces the diff --git a/modus/changelog.mdx b/modus/changelog.mdx index e1606406..760a35c3 100644 --- a/modus/changelog.mdx +++ b/modus/changelog.mdx @@ -4,20 +4,22 @@ description: "The latest changes and improvements in Modus" "og:title": "Changelog - Modus" --- -Welcome to the Modus changelog! Here you'll find the latest updates, -improvements, and bug fixes for the Modus framework. Stay informed about what's -new and what's changed to make the most out of Modus. +Welcome to the Modus changelog! Here you'll find the latest improvements to the +Modus framework. Stay informed about what's new and what's changed to make the +most out of Modus. -## Version history +Here's a short summary of the larger items shipped with each major or minor +release. For a more detailed list of changes, please refer to +[the full change log in GitHub](https://github.com/hypermodeinc/modus/blob/main/CHANGELOG.md). -| Version | Date | Description | -| ------- | ---------- | ----------------------------------------------------- | -| 0.16 | 2024-12-23 | Local time and time zone support | -| 0.15 | 2024-12-13 | Neo4j support | -| 0.14 | 2024-11-23 | Modus API Explorer + in-code documentation | -| 0.13 | 2024-10-17 | First release of Modus as an open source framework 🎉 | +## Version history -For a detailed list of changes, please refer to the -[Changelog in GitHub](https://github.com/hypermodeinc/modus/blob/main/CHANGELOG.md). +| Version | Date | Description | +| ------- | ---------- | ------------------------------------------------------------ | +| 0.17.x | 2025-01-24 | MySQL support, local model tracing, and OpenAI improvements. | +| 0.16.x | 2024-12-23 | Local time and time zone support | +| 0.15.x | 2024-12-13 | Neo4j support | +| 0.14.x | 2024-11-23 | Modus API Explorer + in-code documentation | +| 0.13.x | 2024-10-17 | First release of Modus as an open source framework 🎉 | Stay tuned for more updates and improvements as we continue to enhance Modus! diff --git a/modus/overview.mdx b/modus/overview.mdx index 5c3e04c0..74c32413 100644 --- a/modus/overview.mdx +++ b/modus/overview.mdx @@ -5,8 +5,6 @@ mode: "wide" "og:title": "Overview - Modus" --- ---- - ## What is Modus? {/* */} Modus is an open source, serverless framework for building functions and APIs, diff --git a/modus/sdk/collections.mdx b/modus/sdk/assemblyscript/collections.mdx similarity index 85% rename from modus/sdk/collections.mdx rename to modus/sdk/assemblyscript/collections.mdx index 169aecb9..9974285f 100644 --- a/modus/sdk/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -1,37 +1,33 @@ --- -title: Collections +title: "Collections APIs" +sidebarTitle: "Collections" description: "Add storage and vector search capabilities to your functions." +icon: "circle-small" +iconType: "solid" --- -The Modus Collection API allows you to add vector search within your functions. +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" -## Import + -To begin, import the `collections` namespace from the SDK: +The Modus Collection APIs allow you to add vector search within your functions. - +## Import -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/collections -``` +To begin, import the `collections` namespace from the SDK: -```ts AssemblyScript +```ts import { collections } from "@hypermode/modus-sdk-as" ``` - - ## Collections APIs {/* */} The APIs in the `collections` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Mutation Functions @@ -44,8 +40,8 @@ Inserts or updates an item in a collection. not, it creates a new one. -```go -collections.upsert( +```ts +function upsert( collection: string, key: string | null, text: string, @@ -56,11 +52,11 @@ collections.upsert( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - The unique identifier for the item in the namespace. If null, the function + The unique identifier for the item in the namespace. If `null`, the function generates a unique identifier. @@ -86,8 +82,8 @@ Inserts or updates a batch of items into a collection. with the new text. -```go -collections.upsertBatch( +```ts +function upsertBatch( collection: string, keys: string[] | null, texts: string[], @@ -98,7 +94,7 @@ collections.upsertBatch( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). @@ -123,8 +119,8 @@ collections.upsertBatch( Removes an item from the collection. -```go -collections.remove( +```ts +function remove( collection: string, key: string, namespace: string = "", @@ -133,7 +129,7 @@ collections.remove( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). @@ -147,178 +143,146 @@ collections.remove( ### Search and Retrieval Functions -#### search - -Perform a natural language search on items within a collection. This method is -useful for finding items that match a search query based on semantic meaning. +#### computeDistance - - Modus uses the same embedder for both inserting text into the collection, and - for the text used when searching the collection. - +Computes distance between two keys in a collection using a search method's +embedder. -```go -collections.search( +```ts +function computeDistance( collection: string, searchMethod: string, - text: string, - limit: i32, - returnText: bool = false, - namespaces: string[] = [], -): CollectionSearchResult + key1: string, + key2: string, + namespace: string = "", +): CollectionSearchResultObject ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - The search method used to calculate embedding for text & search against. - - - - The text to compute natural language search on. - - - - The number of result objects to return. + The search method used to calculate embedding for key's texts. - - A flag to return the texts in the response. + + Keys to compute similarity on. - - A list of namespaces to search the item from. Defaults to the default - namespace if not provided. + + The namespace to search the items from. Defaults to the default namespace if + not provided. -#### searchByVector - -Perform a vector-based search on a collection, which is helpful for scenarios -requiring precise similarity calculations between pre-computed embeddings. +#### getLabels - - Modus uses the same embedder for both inserting text into the collection, and - for the vector used when searching the collection. - +Get the labels for an item in a collection. -```go -collections.searchByVector( +```ts +function getLabels( collection: string, - searchMethod: string, - vector: f64[], - limit: i32, - returnText: bool = false, - namespaces: string[] = [], -): CollectionSearchResult + key: string, + namespace: string = "", +): string[] ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - - The search method used to calculate embedding for vector & search against. + + The key of the item to retrieve. - - The vector to compute search on. + + The namespace to get the item from. Defaults to the default namespace if not + provided. - - The number of result objects to return. - +#### getNamespaces - - A flag to return the texts in the response. - +Get all namespaces in a collection. - - An optional array of namespaces to search within. +```ts +function getNamespaces(collection: string): string[] +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). -#### nnClassify +#### getText -Classify an item in the collection using previous vectors' labels. +Gets an item's text from a collection, give the item's key. -```go - collections.nnClassify( +```ts +function getText( collection: string, - searchMethod: string, - text: string, + key: string, namespace: string = "", -): CollectionClassificationResult +): string ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - - The search method used to calculate embedding for text & search against. - - - - The text to compute natural language search on. + + The key of the item to retrieve. - The namespace to search the items from. Defaults to the default namespace if - not provided. + The namespace to get the item from. Defaults to the default namespace if not + provided. -#### computeDistance +#### getTexts -Computes distance between two keys in a collection using a search method's -embedder. +Get all items from a collection. The result is a map of key to text for all +items in the collection. -```go -collections.computeDistance( +```ts +function getTexts( collection: string, - searchMethod: string, - key1: string, - key2: string, namespace: string = "", -): CollectionSearchResultObject +): Map ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). - - - - The search method used to calculate embedding for key's texts. - - - - Keys to compute similarity on. + manifest](/modus/app-manifest#collections). - The namespace to search the items from. Defaults to the default namespace if - not provided. + The namespace to get the items from. Defaults to the default namespace if not + provided. -#### getText +#### getVector -Gets an item's text from a collection, give the item's key. +Get the vector for an item in a collection. -```go -collections.getText( +```ts +function getVector( collection: string, + searchMethod: string, key: string, namespace: string = "", -): string +): f32[] ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). + + + + The search method used to calculate embedding for key's texts. @@ -330,98 +294,128 @@ collections.getText( provided. -#### getTexts +#### nnClassify -Get all items from a collection. The result is a map of key to text for all -items in the collection. +Classify an item in the collection using previous vectors' labels. -```go -collections.getTexts( +```ts +function nnClassify( collection: string, + searchMethod: string, + text: string, namespace: string = "", -): Map +): CollectionClassificationResult ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - - The namespace to get the items from. Defaults to the default namespace if not - provided. + + The search method used to calculate embedding for text & search against. -#### getNamespaces - -Get all namespaces in a collection. - -```go -collections.getNamespaces( - collection: string, -): string[] -``` + + The text to compute natural language search on. + - - Name of the collection, as [defined in the - manifest](../app-manifest#collections). + + The namespace to search the items from. Defaults to the default namespace if + not provided. -#### getVector +#### search -Get the vector for an item in a collection. +Perform a natural language search on items within a collection. This method is +useful for finding items that match a search query based on semantic meaning. + + + Modus uses the same embedder for both inserting text into the collection, and + for the text used when searching the collection. + -```go -collections.getVector( +```ts +function search( collection: string, searchMethod: string, - key: string, - namespace: string = "", -): f64[] + text: string, + limit: i32, + returnText: bool = false, + namespaces: string[] = [], +): CollectionSearchResult ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - The search method used to calculate embedding for key's texts. + The search method used to calculate embedding for text & search against. - - The key of the item to retrieve. + + The text to compute natural language search on. - - The namespace to get the item from. Defaults to the default namespace if not - provided. + + The number of result objects to return. -#### getLabels + + A flag to return the texts in the response. + -Get the labels for an item in a collection. + + A list of namespaces to search the item from. Defaults to the default + namespace if not provided. + + +#### searchByVector + +Perform a vector-based search on a collection, which is helpful for scenarios +requiring precise similarity calculations between pre-computed embeddings. + + + Modus uses the same embedder for both inserting text into the collection, and + for the vector used when searching the collection. + -```go -collections.getLabels( +```ts +function searchByVector( collection: string, - key: string, - namespace: string = "", -): string[] + searchMethod: string, + vector: f32[], + limit: i32, + returnText: bool = false, + namespaces: string[] = [], +): CollectionSearchResult ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). - - The key of the item to retrieve. + + The search method used to calculate embedding for vector & search against. - - The namespace to get the item from. Defaults to the default namespace if not - provided. + + The vector to compute search on. + + + + The number of result objects to return. + + + + A flag to return the texts in the response. + + + + An optional array of namespaces to search within. ### Maintenance Functions @@ -433,17 +427,17 @@ resource-intensive, use it when necessary, for example after you have updated the method for embedding calculation and want to re-compute the embeddings for existing data in the collection. -```go -collections.recomputeSearchMethod( +```ts +function recomputeSearchMethod( collection: string, searchMethod: string, namespace: string = "", -): collections.SearchMethodMutationResult +): SearchMethodMutationResult ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). @@ -454,23 +448,23 @@ collections.recomputeSearchMethod( The namespace to use. Defaults to the default namespace if not provided. -### Objects +### Types #### CollectionMutationResult -```go +Represents the result of a mutation operation on a collection. + +```ts class CollectionMutationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - operation: string; - keys: string[]; + collection: string + status: CollectionStatus + error: string + isSuccessful: bool + operation: string + keys: string[] } ``` -Represents the result of a mutation operation on a collection. - Name of the collection. @@ -496,20 +490,40 @@ Represents the result of a mutation operation on a collection. The keys of the items affected by the operation. -#### CollectionSearchResult +#### CollectionClassificationLabelObject -```go -class CollectionSearchResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - searchMethod: string; - objects: CollectionSearchResultObject[]; +Represents a classification label. + +```ts +class CollectionClassificationLabelObject { + label: string + confidence: f64 } ``` -Represents the result of a search operation on a collection. + + The classification label. + + + + The confidence score of the classification label. + + +#### CollectionClassificationResult + +Represents the result of a classification operation on a collection. + +```ts +class CollectionClassificationResult { + collection: string + status: CollectionStatus + error: string + isSuccessful: bool + searchMethod: string + labelsResult: CollectionClassificationLabelObject[] + cluster: CollectionClassificationResultObject[] +} +``` Name of the collection. @@ -532,61 +546,58 @@ Represents the result of a search operation on a collection. The search method used in the operation. - - The search results. + + The classification labels. -#### CollectionSearchResultObject + + The classification results. + -```go -class CollectionSearchResultObject { - namespace: string; - key: string; - text: string; - labels: string[]; - distance: f64; - score: f64; -} -``` +#### CollectionClassificationResultObject -Represents an object in the search results. +Represents an object in the classification results. - - The namespace of the item found as part of the search. - +```ts +class CollectionClassificationResultObject { + key: string + labels: string[] + distance: f64 + score: f64 +} +``` - The key of the item found as part of the search. + The key of the item classified. - - The text of the item found as part of the search. + + The classification labels. - The distance of the item from the search text. + The distance of the item from the classification labels. - The similarity score of the item found, as it pertains to the search. + The similarity score of the item classified. -#### CollectionClassificationResult +#### CollectionSearchResult -```go -class CollectionClassificationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - searchMethod: string; - labelsResult: CollectionClassificationLabelObject[]; - cluster: CollectionClassificationResultObject[]; +Represents the result of a search operation on a collection. + +```ts +class CollectionSearchResult { + collection: string + status: CollectionStatus + error: string + isSuccessful: bool + searchMethod: string + objects: CollectionSearchResultObject[] } ``` -Represents the result of a classification operation on a collection. - Name of the collection. @@ -608,73 +619,56 @@ Represents the result of a classification operation on a collection. The search method used in the operation. - - The classification labels. + + The search results. - - The classification results. - +#### CollectionSearchResultObject -#### CollectionClassificationLabelObject +Represents an object in the search results. -```go -class CollectionClassificationLabelObject { - label: string; - confidence: f64; +```ts +class CollectionSearchResultObject { + namespace: string + key: string + text: string + labels: string[] + distance: f64 + score: f64 } ``` -Represents a classification label. - - - The classification label. - - - - The confidence score of the classification label. + + The namespace of the item found as part of the search. -#### CollectionClassificationResultObject - -```go -class CollectionClassificationResultObject { - key: string; - labels: string[]; - distance: f64; - score: f64; -} -``` - -Represents an object in the classification results. - - The key of the item classified. + The key of the item found as part of the search. - - The classification labels. + + The text of the item found as part of the search. - The distance of the item from the classification labels. + The distance of the item from the search text. - The similarity score of the item classified. + The similarity score of the item found, as it pertains to the search. #### CollectionStatus -```go +The status of a collection operation. + +```ts enum CollectionStatus { - Success = "success"; - Error = "error"; + Success = "success" + Error = "error" } ``` -The status of a collection operation. - The operation was successful. @@ -685,19 +679,19 @@ The status of a collection operation. #### SearchMethodMutationResult -```go +Represents the result of a mutation operation on a search method. + +```ts class SearchMethodMutationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - operation: string; - searchMethod: string; + collection: string + status: CollectionStatus + error: string + isSuccessful: bool + operation: string + searchMethod: string } ``` -Represents the result of a mutation operation on a search method. - Name of the collection. diff --git a/modus/sdk/console.mdx b/modus/sdk/assemblyscript/console.mdx similarity index 72% rename from modus/sdk/console.mdx rename to modus/sdk/assemblyscript/console.mdx index edd3e3bd..3a6c34cb 100644 --- a/modus/sdk/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -1,17 +1,25 @@ --- -title: Console +title: "Console APIs" +sidebarTitle: "Console" description: "Capture errors and debugging information in your functions" +icon: "circle-small" +iconType: "solid" --- -The Modus Console API allows you to capture information from your functions, +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Console APIs allow you to capture information from your functions, such as errors and other information that can help you debug your functions. - Unlike other APIs, the Console API is globally available by default in all - functions, you don't need to import it. + Unlike other APIs, the `console` namespace is globally available by default in + all AssemblyScript functions, you don't need to import it. -The Console API mimics the behavior of the AssemblyScript +The Console APIs mimic the behavior of the AssemblyScript [`console`](https://www.assemblyscript.org/stdlib/console.html) object, but directs the output to Hypermode as follows: @@ -27,11 +35,7 @@ directs the output to Hypermode as follows: The APIs in the `console` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Assertion Functions @@ -39,11 +43,11 @@ The APIs in the `console` namespace are below, organized by category. Asserts that a condition is true, and logs an error if it's not. -```go -console.assert(assertion: any, message?: string): void +```ts +function assert(assertion: T, message?: string): void ``` - + The condition to assert. Typically a boolean value. In the case of an object, asserts that the object isn't `null`. @@ -58,8 +62,8 @@ console.assert(assertion: any, message?: string): void Generate a log message, with no particular logging level. -```go -console.log(message?: string): void +```ts +function log(message?: string): void ``` @@ -70,8 +74,8 @@ console.log(message?: string): void Generate a log message with the "debug" logging level. -```go -console.debug(message?: string): void +```ts +function debug(message?: string): void ``` @@ -82,8 +86,8 @@ console.debug(message?: string): void Generate a log message with the "info" logging level. -```go -console.info(message?: string): void +```ts +function info(message?: string): void ``` @@ -94,8 +98,8 @@ console.info(message?: string): void Generate a log message with the "warning" logging level. -```go -console.warn(message?: string): void +```ts +function warn(message?: string): void ``` @@ -106,8 +110,8 @@ console.warn(message?: string): void Generate a log message with the "error" logging level. -```go -console.error(message?: string): void +```ts +function error(message?: string): void ``` @@ -120,8 +124,8 @@ console.error(message?: string): void Starts a new timer using the specified label. -```go -console.time(label?: string): void +```ts +function time(label?: string): void ``` @@ -132,8 +136,8 @@ console.time(label?: string): void Logs the current value of a timer previously started with `console.time`. -```go -console.timeLog(label?: string): void +```ts +function timeLog(label?: string): void ``` @@ -145,8 +149,8 @@ console.timeLog(label?: string): void Logs the current value of a timer previously started with `console.time`, and discards the timer. -```go -console.timeEnd(label?: string): void +```ts +function timeEnd(label?: string): void ``` diff --git a/modus/sdk/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx similarity index 67% rename from modus/sdk/dgraph.mdx rename to modus/sdk/assemblyscript/dgraph.mdx index 253f9059..aacff039 100644 --- a/modus/sdk/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -1,145 +1,151 @@ --- -title: Dgraph +title: "Dgraph APIs" +sidebarTitle: "Dgraph" description: "Execute queries and mutations against a Dgraph database" +icon: "circle-small" +iconType: "solid" --- -The Modus Dgraph API allows you to run queries and mutations against a Dgraph +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph database. ## Import To begin, import the `dgraph` namespace from the SDK: - - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/dgraph -``` - -```ts AssemblyScript +```ts import { dgraph } from "@hypermode/modus-sdk-as" ``` - - ## Dgraph APIs {/* */} The APIs in the `dgraph` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Functions -#### execute +#### alterSchema -Execute a Dgraph query or mutation using a Dgraph Request object. +Alter the schema of a Dgraph database. -```go -function execute(connectionName: string, request: Request): Response; +```ts +function alterSchema(connection: string, schema: string): string ``` - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](/modus/app-manifest#connections). - - A Dgraph [`Request`](#request) object, describing the query or mutation to - execute. + + The schema to apply to the Dgraph database. -#### alterSchema +#### dropAll -Alter the schema of a Dgraph database. +Drop all data from a Dgraph database. -```go -function alterSchema(connectionName: string, schema: string): string; +```ts +function dropAll(connection: string): string ``` - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). - - - - The schema to apply to the Dgraph database. + manifest](/modus/app-manifest#connections). #### dropAttr Drop an attribute from a Dgraph schema. -```go -function dropAttr(connectionName: string, attr: string): string; +```ts +function dropAttr(connection: string, attr: string): string ``` - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](/modus/app-manifest#connections). The attribute to drop from the Dgraph schema. -#### dropAll +#### execute -Drop all data from a Dgraph database. +Execute a Dgraph query or mutation using a Dgraph Request object. -```go -function dropAll(connectionName: string): string; +```ts +function execute(connection: string, request: Request): Response ``` - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](/modus/app-manifest#connections). + + + + A Dgraph [`Request`](#request) object, describing the query or mutation to + execute. -### Objects +### Types -#### Request +#### Mutation -A Dgraph request object, used to execute queries and mutations. +A Dgraph mutation object, used to execute mutations. -```go -class Request { - constructor(Query: Query | null = null, Mutations: Mutation[] | null = null); - query: Query = new Query(); - mutations: Mutation[] = []; +```ts +class Mutation { + setJson: string, + delJson: string, + setNquads: string, + delNquads: string, + condition: string, } ``` - - Creates a new `Request` object with the given `query` and `mutations`. + + Creates a new `Mutation` object with the given `setJson`, `delJson`, + `setNquads`, `delNquads`, and `condition` fields. + -The [`query`](#query) and [`mutations`](#mutation) fields are optional and -default to `null`. + + A JSON string representing the data to set in the mutation. + + + A JSON string representing the data to delete in the mutation. - - A Dgraph [`query`](#query) object. + + A string representing the data to set in the mutation in NQuads format. - - An array of Dgraph [`mutation`](#mutation) objects. + + A string representing the data to delete in the mutation in NQuads format. + + + + A string representing the condition query for the mutation. #### Query A Dgraph query object, used to execute queries. -```go +```ts class Query { - constructor(query: string = "", variables: Variables = new Variables()); - query: string = ""; - variables: Map = new Map(); + query: string = "" + variables: Map = new Map() } ``` @@ -157,63 +163,50 @@ class Query { A map of query variables. -#### Variables +#### Request -A Variables object used to set query variables in a Dgraph query. +A Dgraph request object, used to execute queries and mutations. -```go -class Variables { - public set(name: string, value: T): void; - public toMap(): Map; +```ts +class Request { + query: Query = new Query() + mutations: Mutation[] = [] } ``` - - Sets a query variable with the given `name` and `value`. `name` is of type - `string`, and `value` can be of any type. - - - - Returns a map of all query variables set in the `Variables` object. - - -#### Mutation + -A Dgraph mutation object, used to execute mutations. +Creates a new `Request` object with the given `query` and `mutations`. -```go -class Mutation { - constructor( - public setJson: string = "", - public delJson: string = "", - public setNquads: string = "", - public delNquads: string = "", - public condition: string = "", - ) -} -``` +The [`query`](#query) and [`mutations`](#mutation) fields are optional and +default to `null`. - - Creates a new `Mutation` object with the given `setJson`, `delJson`, - `setNquads`, `delNquads`, and `condition` fields. - - A JSON string representing the data to set in the mutation. + + A Dgraph [`query`](#query) object. - - A JSON string representing the data to delete in the mutation. + + An array of Dgraph [`mutation`](#mutation) objects. - - A string representing the data to set in the mutation in NQuads format. - +#### Variables - - A string representing the data to delete in the mutation in NQuads format. +A Variables object used to set query variables in a Dgraph query. + +```ts +class Variables { + set(name: string, value: T): void + toMap(): Map +} +``` + + + Sets a query variable with the given `name` and `value`. `name` is of type + `string`, and `value` can be of any type. - - A string representing the condition query for the mutation. + + Returns a map of all query variables set in the `Variables` object. diff --git a/modus/sdk/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx similarity index 71% rename from modus/sdk/graphql.mdx rename to modus/sdk/assemblyscript/graphql.mdx index 94d2269e..59e357d5 100644 --- a/modus/sdk/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -1,77 +1,77 @@ --- -title: GraphQL +title: "GraphQL APIs" +sidebarTitle: "GraphQL" description: "Access external GraphQL data sources from your functions" +icon: "circle-small" +iconType: "solid" --- -The Modus GraphQL API allows you to securely call and fetch data from any +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus GraphQL APIs allow you to securely call and fetch data from any GraphQL endpoint. ## Import To begin, import the `graphql` namespace from the SDK: - - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/graphql +```ts +import { graphql } from "@hypermode/modus-sdk-as" ``` -```ts AssemblyScript -import { http } from "@hypermode/modus-sdk-as" -``` - - - ## GraphQL APIs {/* */} The APIs in the `graphql` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Functions #### execute Execute a GraphQL statement to call a query or apply mutation against a GraphQL -API endpoint. +endpoint. -```go -graphql.execute ( +```ts +function execute( connection: string, statement: string, - variables?: Variables + variables?: Variables, ): Response ``` - + Type of object to use for the data returned from the query. This can be any type, including a custom type defined in your project. It should match the shape of the data returned from the GraphQL query. - - Define custom types in the project's source code. In AssemblyScript, create classes decorated with `@json`. + + +Define custom types in the project's source code. In AssemblyScript, create +classes decorated with `@json`. All types, including classes, base classes, and field types must be JSON serializable. You can also use built-in types such as strings, numbers, arrays, and maps. - + + Name of the connection, as [defined in the - manifest](../app-manifest#connection). + manifest](/modus/app-manifest#connection). - GraphQL statement containing the query or mutation operation to execute. + +GraphQL statement containing the query or mutation operation to execute. While it's possible to directly include parameter values into your GraphQL @@ -83,46 +83,55 @@ and maps. - Optional variables to include with the query. + +Optional variables to include with the query. See the details of the [`Variables`](#variables) object for more information. -### Objects +### Types #### Variables -```go -class Variables { - public set(name: string, value: any): void; - public toJSON(): string; -} -``` - A container for variables to include with a GraphQL operation. To use this feature, create a new `Variables` object and call the `set` method for each variable you want to include. Then pass the object to the `execute` function. +```ts +class Variables { + set(name: string, value: T): void + toJSON(): string +} +``` + - Set a variable with a name and value to include with the GraphQL operation. -{" "} +Set a variable with a name and value to include with the GraphQL operation. + + +{/* */} The name of the variable to include in the GraphQL operation. - - The value of the variable to include in the GraphQL operation. + + +The value of the variable to include in the GraphQL operation. The value can be of any type that's JSON serializable, including strings, numbers, boolean values, arrays, maps, and custom objects decorated with `@json`. + +{/* */} + + + @@ -133,19 +142,20 @@ numbers, boolean values, arrays, maps, and custom objects decorated with #### Response -```go -class Response { - errors: ErrorResult[] | null; - data: T | null; -} -``` - A response object from the GraphQL query. Either `errors` or `data` is present, depending on the result of the query. +```ts +class Response { + errors: ErrorResult[] | null + data: T | null +} +``` + - An array of errors incurred as part of your GraphQL request, if any. + +An array of errors incurred as part of your GraphQL request, if any. Each error in the array is an [`ErrorResult`](#errorresult) object. If there are no errors, this field is `null`. @@ -153,7 +163,8 @@ no errors, this field is `null`. - The resulting data selected by the GraphQL operation. + +The resulting data selected by the GraphQL operation. The data has the type specified in the call to the `execute` function. If data is absent due to errors, this field is `null`. @@ -162,43 +173,44 @@ is absent due to errors, this field is `null`. #### ErrorResult -```go +The details of an error incurred as part of a GraphQL operation. + +```ts class ErrorResult { - message: string; - locations: CodeLocation[] | null; - path: string[] | null; + message: string + locations: CodeLocation[] | null + path: string[] | null } ``` -The details of an error incurred as part of a GraphQL operation. - Description of the error incurred. + + An array of [`CodeLocation`](#codelocation) objects that point to the specific + location of the error in the GraphQL statement. + + - Path to the area of the GraphQL statement related to the error. + +Path to the area of the GraphQL statement related to the error. Each item in the array represents a segment of the path. - - An array of [`CodeLocation`](#codelocation) objects that point to the specific - location of the error in the GraphQL statement. - - #### CodeLocation -```go +The location of specific code within a GraphQL statement. + +```ts class CodeLocation { - line: u32; - column: u32; + line: u32 + column: u32 } ``` -The location of specific code within a GraphQL statement. - Line number within the GraphQL statement for the code. diff --git a/modus/sdk/http.mdx b/modus/sdk/assemblyscript/http.mdx similarity index 63% rename from modus/sdk/http.mdx rename to modus/sdk/assemblyscript/http.mdx index dc860b12..ca8e76b2 100644 --- a/modus/sdk/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -1,17 +1,27 @@ --- -title: HTTP +title: "HTTP APIs" +sidebarTitle: "HTTP" description: "Access external HTTP endpoints from your functions" +icon: "circle-small" +iconType: "solid" --- -The Modus HTTP API allows you to securely call and fetch data from an HTTP +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus HTTP APIs allow you to securely call and fetch data from an HTTP endpoint. It's similar to the HTTP [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API used in -JavaScript, but with some modifications to work with Hypermode Functions. +JavaScript, but with some modifications to work with Modus. - - As a security measure, you can only call HTTP endpoints that you - [defined in your app's manifest](../app-manifest#connections). Any attempt to access an arbitrary URL, for a connection not - defined in your app's manifest, results in an error. + + +As a security measure, you can only call HTTP endpoints that you +[defined in your app's manifest](/modus/app-manifest#connections). Any attempt +to access an arbitrary URL, for a connection not defined in your app's manifest, +results in an error. Additionally, you should use placeholders for connection secrets in the manifest, rather than hardcoding them in your functions. Enter the values for @@ -19,35 +29,23 @@ each connections' secrets via environment variables or the Hypermode UI. This ensures that your secrets are securely stored, aren't committed to your repository, and aren't visible or accessible from your functions code. - + ## Import To begin, import the `http` namespace from the SDK: - - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/http -``` - -```ts AssemblyScript +```ts import { http } from "@hypermode/modus-sdk-as" ``` - - ## HTTP APIs {/* */} The APIs in the `http` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Functions @@ -57,23 +55,28 @@ Invoke an HTTP endpoint to retrieve data or trigger external action. Returns a [`Response`](#response) object with the HTTP response data. -```go -http.fetch( +```ts +function fetch( requestOrUrl: string | Request, options: RequestOptions = new RequestOptions(), ): Response ``` - Either a URL `string` or a [`Request`](#request) object, describing the HTTP request to make. + +Either a URL `string` or a [`Request`](#request) object, describing the HTTP +request to make. If a `string`, the operation uses the `GET` HTTP method with no headers other than those defined in the manifest entry of the connection. - - Each request must match to a connection entry in the manifest, using the `baseUrl` field. The request URL passed to the - `fetch` function (or via a `Request` object) must start with the manifest entry's `baseUrl` value to match. - + + Each request must match to a connection entry in the manifest, using the + `baseUrl` field. The request URL passed to the `fetch` function (or via a + `Request` object) must start with the manifest entry's `baseUrl` value to + match. + + @@ -81,27 +84,41 @@ than those defined in the manifest entry of the connection. request, such as the HTTP method, headers, and body. -### Objects +### Types #### Content -```go +Represents content used in the body of an HTTP request or response. + +```ts class Content { - static from(value: any): Content; - readonly data: ArrayBuffer; - text(): string; - json(): T; + static from(value: T): Content + readonly data: ArrayBuffer + bytes(): Uint8Array + text(): string + json(): T } ``` -Represents content used in the body of an HTTP request or response. - - Creates a new `Content` object from the given value. + +Creates a new `Content` object from the given value. + +The value can be of any type that's JSON serializable, including strings, +numbers, boolean values, arrays, maps, and custom objects decorated with +`@json`. + +If the value is a `string` or an `ArrayBuffer` it's sent as-is, without JSON +serialization. + - The raw binary content data. + The raw binary content data buffer. + + + + Returns the binary content data as a `Uint8Array`. @@ -116,15 +133,15 @@ Represents content used in the body of an HTTP request or response. #### Header -```go +Represents an HTTP request or response header. + +```ts class Header { - name: string; - values: string[]; + name: string + values: string[] } ``` -Represents an HTTP request or response header. - The name of the header. @@ -136,23 +153,24 @@ Represents an HTTP request or response header. #### Headers -```go +Represents a collection of HTTP headers. + +```ts class Headers { static from( value: string[][] | Map | Map, - ): Headers; - append(name: string, value: string): void; - entries(): string[][]; - get(name: string): string | null; + ): Headers + append(name: string, value: string): void + entries(): string[][] + get(name: string): string | null } ``` -Represents a collection of HTTP headers. - - Creates a new `Headers` object from the given `value` object. -The `value` object must be one of the following types: +Creates a new `Headers` object from the given `value`. + +The `value` must be one of the following types: - A `string[][]`, where each inner array contains a header name and value. - A `Map`, where the keys are header names and the values are @@ -179,23 +197,25 @@ The `value` object must be one of the following types: #### Request -```go +Represents an HTTP request to make. + +```ts class Request { - constructor(url: string, options?: RequestOptions); - static clone(request: Request, options: RequestOptions): Request; - readonly url: string; - readonly method: string; - readonly headers: Headers; - readonly body: ArrayBuffer; - text(): string; - json(): T; + constructor(url: string, options?: RequestOptions) + static clone(request: Request, options: RequestOptions): Request + readonly url: string + readonly method: string + readonly headers: Headers + readonly body: ArrayBuffer + bytes(): Uint8Array + text(): string + json(): T } ``` -Represents an HTTP request to make. - - Creates a new `Request` object with the given `url` and `options`. + +Creates a new `Request` object with the given `url` and `options`. The required `url` parameter must be a fully qualified URL of the request, including the protocol. For example, `"https://example.com"`. @@ -225,7 +245,18 @@ that's used to set the HTTP method, headers, and body if needed. - The raw binary content data of the request body. + +The raw binary content data buffer of the request body. + + + The request body isn't normally read directly. Instead, use the `bytes`, + `text` or `json` functions. + + + + + + Returns the binary content data of the request body as a `Uint8Array`. @@ -240,53 +271,61 @@ that's used to set the HTTP method, headers, and body if needed. #### RequestOptions -```go +Options for the HTTP request. + +```ts class RequestOptions { - method: string | null; - headers: Headers; - body: Content | null; + method: string | null + headers: Headers + body: Content | null } ``` -Options for the HTTP request. - The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or `"DELETE"`. If `null` (the default), the request uses the `GET` method. - The HTTP headers of the request, as a [`Headers`](#headers) object. - - By default, the `RequestOptions` contains an empty `Headers` object which you can add headers to using the `append` - method. - +The HTTP headers of the request, as a [`Headers`](#headers) object. + + + By default, the `RequestOptions` contains an empty `Headers` object which you + can add headers to using the `append` method. + + - Content to pass in the request body, as a [`Content`](#content) object, or `null` (the default) if there is no body to - pass. - It's generally recommended to supply a `Content-Type` header for any requests that have a body. +Content to pass in the request body, as a [`Content`](#content) object, or +`null` (the default) if there is no body to pass. + + + It's generally recommended to supply a `Content-Type` header for any requests + that have a body. + + #### Response -```go +Represents the response received from the HTTP server. + +```ts class Response { - readonly status: u16; - readonly statusText: string; - readonly headers: Headers; - readonly body: ArrayBuffer; - readonly ok: bool; - text(): string; - json(): T; + readonly status: u16 + readonly statusText: string + readonly headers: Headers + readonly body: ArrayBuffer + readonly ok: bool + bytes(): Uint8Array + text(): string + json(): T } ``` -Represents the response received from the HTTP server. - The HTTP response status code, such as `200` for success. @@ -302,12 +341,23 @@ Represents the response received from the HTTP server. - The raw binary content data of the response body. - - The response body isn't normally read directly. Instead, use the `text` or `json` functions. You should only read the - `body` directly if you expect to receive binary data in the response. - +The raw binary content data buffer of the response body. + + + The response body isn't normally read directly. Instead, use the `bytes`, + `text` or `json` functions. + + + + + + A boolean value indicating whether the response was successful. It's `true` if + the status code is in the range `200-299`, and `false` otherwise. + + + + Returns the binary content data of the response body as a `Uint8Array`. diff --git a/modus/sdk/assemblyscript/localtime.mdx b/modus/sdk/assemblyscript/localtime.mdx new file mode 100644 index 00000000..a2565727 --- /dev/null +++ b/modus/sdk/assemblyscript/localtime.mdx @@ -0,0 +1,137 @@ +--- +title: "Local Time APIs" +sidebarTitle: "Local Time" +description: "Access the user's local time and time zone in your functions" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Local Time APIs allow you to access the user's local time and time +zone from your functions. + +## Import + +To begin, import the `localtime` namespace from the SDK: + +```ts +import { localtime } from "@hypermode/modus-sdk-as" +``` + +{/* */} + +## Local Time APIs + +The APIs in the `localtime` namespace are below. + +All time zones use the IANA time zone database format. For example, +`"America/New_York"`. You can find a list of valid time zones +[here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + + + +{/* */} + +For APIs that work with the user's local time, the time zone is determined in +the following order of precedence: + +- If the `X-Time-Zone` header is present in the request, the time zone is set to + the value of the header. +- If the `TZ` environment variable is set on the host, the time zone is set to + the value of the variable. +- Otherwise, the time zone is set to the host's local time zone. + +{/* */} + + + + + +When working locally with `modus dev`, Modus uses the host's local time zone by +default. You can override this by setting the `TZ` environment variable in your +`.env.local` file. + + + + + +In a browser-based web app, you can get the user's time zone with the following +JavaScript code: + +```js +const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone +``` + +Assign that value to a `"X-Time-Zone"` request header when calling Modus, to use +it for all local time calculations. + + + + + +If you just need the current UTC time, you can use AssemblyScript's built-in +support: + +```ts +const now = new Date(Date.now()) + +// if you need a string +const utcTime = now.toISOString() +``` + + + + + +### Functions + +#### getTimeZone + +Returns the user's time zone in IANA format. + +```ts +function getTimeZone(): string +``` + +#### isValidTimeZone + +Determines whether the specified time zone is a valid IANA time zone and +recognized by the system as such. + +```ts +function isValidTimeZone(tz: string): bool +``` + + + An IANA time zone identifier, such as `"America/New_York"`. + + +#### now + +Returns the current local time in the user's time zone, as a string in ISO 8601 +extended format, including the applicable time zone offset. + +For example, `"2025-12-31T12:34:56.789-04:00"`. + +```ts +function now(): string +``` + +#### nowInZone + +Returns the current local time in a specified time zone, as a string in ISO 8601 +extended format, including the applicable time zone offset. + +For example, `"2025-12-31T12:34:56.789-04:00"`. + +```ts +function nowInZone(tz: string): string +``` + + + An IANA time zone identifier, such as `"America/New_York"`. + diff --git a/modus/sdk/models.mdx b/modus/sdk/assemblyscript/models.mdx similarity index 55% rename from modus/sdk/models.mdx rename to modus/sdk/assemblyscript/models.mdx index 404b4778..127b1251 100644 --- a/modus/sdk/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -1,22 +1,30 @@ --- -title: Models +title: "AI Model APIs" +sidebarTitle: "Models" description: "Invoke AI models from your functions" +icon: "circle-small" +iconType: "solid" --- -The Modus Models API allows you to invoke AI models directly from your +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Models APIs allow you to invoke AI models directly from your functions, irrespective of the model's host. -Since many models have unique interfaces, the design of the Models API is -extremely flexible. A common base class forms the core of the API, which extends -to conform to any model's required schema. +Since many models have unique interfaces, the design of the Models APIs are +extremely flexible. A common base class forms the core of the APIs, which +extends to conform to any model's required schema. -The SDK contains both the base classes and pre-defined implementations for many -commonly used models. You can either use one of the pre-defined classes, or can -create custom classes for any model you like, by extending from the base `Model` -class. +The SDK contains both the base types and pre-defined implementations for many +commonly used models. You can either use one of the pre-defined model types, or +can create custom types for any model you like, by following the same pattern as +implemented in the pre-defined models. -For your reference, several complete examples for using the Models API are available in +For your reference, several complete examples for using the Models APIs are available in [Model Invoking](/modus/model-invoking). Each example demonstrates using different types of AI models for different @@ -29,33 +37,16 @@ use it for any task that an AI model can perform. To begin, import the `models` namespace from the SDK: - - - ```go - import github.com/hypermodeinc/modus/sdk/go/pkg/models - ``` - - You'll also need to import one or more classes for the model you are working with. For example: - - ```go - import github.com/hypermodeinc/modus/sdk/go/pkg/models/experimental - ``` - - - - - ```ts - import { models } from "@hypermode/modus-sdk-as" - ``` - - You'll also need to import one or more classes for the model you are working with. For example: +```ts +import { models } from "@hypermode/modus-sdk-as" +``` - ```ts - import { ClassificationModel } from "@hypermode/modus-sdk-as/models/experimental/classification" - ``` +You'll also need to import one or more classes for the model you are working +with. For example: - - +```ts +import { OpenAIChatModel } from "@hypermode/modus-sdk-as/models/openai" +``` If you would like to request a new model, please [open an issue](https://github.com/hypermodeinc/modus/issues). You can also send @@ -67,11 +58,7 @@ a pull request, if you'd like to contribute a new model yourself. The APIs in the `models` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Functions @@ -79,11 +66,11 @@ The APIs in the `models` namespace are below, organized by category. Get a model instance by name and type. - ```go - models.getModel(modelName: string): T - ``` +```ts +function getModel(modelName: string): T +``` - + The type of model to return. This can be any class that extends the `Model` base class. @@ -93,19 +80,11 @@ Get a model instance by name and type. in your project's manifest file. -### Objects +### Types #### Model - ```go - abstract class Model { - debug: boolean; - info: ModelInfo; - invoke(input: TInput): TOutput; - } - ``` - -The base class for all models that Hypermode functions can invoke. +The base class for all models that Modus functions can invoke. If you are implementing a custom model, you should extend this class. You'll @@ -114,43 +93,43 @@ The base class for all models that Hypermode functions can invoke. for examples. - +```ts +abstract class Model { + debug: bool + info: ModelInfo + invoke(input: TInput): TOutput +} +``` + + The type of the input data for the model. This can be any type, including a custom type defined in your project. It should match the shape of the data expected by the model. It's usually a class. - + The type of the output data from the model. This can be any type, including a custom type defined in your project. It should match the shape of the data returned by the model. It's usually a class. - - A flag to enable debug mode for the model. When enabled, Hypermode - automatically logs the full request and response data to the console. - implementations can also use this flag to enable additional debug logging. - Defaults to `false`. + + A flag to enable debug mode for the model. When enabled, Modus automatically + logs the full request and response data to the console. Implementations can + also use this flag to enable additional debug logging. Defaults to `false`. - Information about the model set by the Hypermode Runtime when creating the + Information about the model set by the Modus Runtime when creating the instance. See the [`ModelInfo`](#modelinfo) object for more information. - + Invokes the model with input data and returns the output data. #### ModelInfo - ```go - class ModelInfo { - readonly name: string; - readonly fullName: string; - } - ``` - Information about a model that's used to construct a `Model` instance. It's also available as a property on the `Model` class. @@ -161,13 +140,18 @@ implementation. Generally, you don't need to create `ModelInfo` instances directly. However, if you are implementing a custom model, you may wish to use a property -from this class, such as the `fullName`, for model providers that require the -model name in the input request body. - -We may add additional properties to this class in the future, as needed. +from this class, such as `fullName`, for model providers that require the model +name in the input request body. +```ts +class ModelInfo { + readonly name: string + readonly fullName: string +} +``` + The name of the model from the app manifest. diff --git a/modus/sdk/assemblyscript/mysql.mdx b/modus/sdk/assemblyscript/mysql.mdx new file mode 100644 index 00000000..baa21343 --- /dev/null +++ b/modus/sdk/assemblyscript/mysql.mdx @@ -0,0 +1,387 @@ +--- +title: "MySQL APIs" +sidebarTitle: "MySQL" +description: "Execute queries against a MySQL database" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus MySQL APIs allow you to run queries against MySQL or any +MySQL-compatible database platform. + +## Import + +To begin, import the `mysql` namespace from the SDK: + +```ts +import { mysql } from "@hypermode/modus-sdk-as" +``` + +## MySQL APIs + +{/* */} + +The APIs in the `mysql` namespace are below, organized by category. + + + +### Functions + +#### execute + +Execute a SQL statement against a MySQL database, without any data returned. Use +this for insert, update, or delete operations, or for other SQL statements that +don't return data. + + + The `execute` function is for operations that don't return data. However, some + insert/update/delete operations may still return data. In these cases, you can + use the `queryScalar` or `query` functions instead. + + +```ts +function execute( + connection: string, + statement: string, + params?: Params, +): Response +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass a [`Params`](#params) object + instead. This can help to protect against injection attacks and other security + vulnerabilities. + + + + + + +Optional parameters to include with the query. + +See the details of the [`Params`](#params) object for more information. + + + +#### query + +Execute a SQL statement against a MySQL database, returning a set of rows. In +the results, each row converts to an object of type `T`, with fields matching +the column names. + +```ts +function query( + connection: string, + statement: string, + params?: Params, +): QueryResponse +``` + + + +Type of object to use for the data returned from the query. This can be any +type, including a custom type defined in your project. It should match the shape +of the row returned from the SQL query. + + + +Define custom types in the app's source code. In AssemblyScript, create classes +decorated with `@json`. + +All types, including classes, base classes, and field types must be JSON +serializable. You can also use built-in types such as strings, numbers, arrays, +and maps. + +If working with MySQL's `point` data type, you can use a [`Point`](#point) or +[`Location`](#location) object to represent the data. + + + + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass a [`Params`](#params) object + instead. This can help to protect against injection attacks and other security + vulnerabilities. + + + + + + +Optional parameters to include with the query. + +See the details of the [`Params`](#params) object for more information. + + + +#### queryScalar + +Execute a SQL statement against a MySQL database, returning a single scalar +value. For example, the result could be a count, sum, or average, or it could be +an identifier. + +```ts +function queryScalar( + connection: string, + statement: string, + params?: Params, +): ScalarResponse +``` + + + Type of object to use for the data returned from the query. This should + generally be a scalar data type, such as a number or string. It should match + the type of the data returned from the SQL query. + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass a [`Params`](#params) object + instead. This can help to protect against injection attacks and other security + vulnerabilities. + + + + + + +Optional parameters to include with the query. + +See the details of the [`Params`](#params) object for more information. + + + +### Types + +#### Location + +Represents a location on Earth, having `longitude` and `latitude` coordinates. + +Correctly serializes to and from MySQL's point type, in (longitude, latitude) +order. + + + This class is identical to the [Point](#point) class, but uses different field + names. + + +```ts +class Location { + longitude: f64, + latitude: f64, +} +``` + + + The longitude coordinate of the location, in degrees. + + + + The latitude coordinate of the location, in degrees. + + +#### Params + +A container for parameters to include with a SQL operation. + +To use this feature, create a new `Params` object and call the `push` method for +each parameter you want to include. Then pass the object to the `execute`, +`query`, or `queryScalar` function along with your SQL statement. + +```ts +class Params { + push(value: T): void + toJSON(): string +} +``` + + + +Push a parameter value into the list included with the SQL operation. The +sequence of calls to `push` determines the order of the parameters in the SQL +statement. This corresponds to the order of the `?` placeholders or `$1`, `$2`, +etc. + + +{/* */} + + + +The value of the parameter to include in the SQL operation. + +The value can be of any type that's JSON serializable, including strings, +numbers, boolean values, arrays, maps, and custom objects decorated with +`@json`, as long as the database supports it. + + + If working with MySQL's `Point` data type, you can either pass separate + parameters for the coordinates and use a `point()` function in the SQL + statement, or you can pass a [`Point`](#point) or [`Location`](#location) + object as a single parameter. + + + + +{/* */} + + + + + + + Serializes the parameters to a JSON string for inclusion in the SQL operation. + The SDK functions call this automatically when you pass a `Params` object. You + typically don't need to call it directly. + + +#### Point + +Represents a point in 2D space, having `x` and `y` coordinates. Correctly +serializes to and from MySQL's point type, in (x, y) order. + + + This class is identical to the [Location](#location) class, but uses different + field names. + + +```ts +class Point { + x: f64, + y: f64, +} +``` + + + The x coordinate of the point. + + + + The y coordinate of the point. + + +#### QueryResponse + +Represents the response from a [`query`](#query) operation. + +```ts +class QueryResponse { + error: string | null + rowsAffected: u32 + lastInsertId: u64 + rows: T[] +} +``` + + + An error message, if an error occurred during the operation. Otherwise, this + field is `null`. + + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + When inserting a row, this field contains the ID of the last inserted row. + This is useful for tables with auto-incrementing primary keys. + + + + An array of objects, each representing a row returned from the query. Each + object has fields corresponding to the columns in the result set. + + +#### Response + +Represents the response from an [`execute`](#execute) operation. Also serves as +the base class for `QueryResponse` and `ScalarResponse`. + +```ts +class Response { + error: string | null + rowsAffected: u32 + lastInsertId: u64 +} +``` + + + An error message, if an error occurred during the operation. Otherwise, this + field is `null`. + + + + The number of rows affected by the operation. + + + + When inserting a row, this field contains the ID of the last inserted row. + This is useful for tables with auto-incrementing primary keys. + + +#### ScalarResponse + +Represents the response from a [`queryScalar`](#queryscalar) operation. + +```ts +class ScalarResponse { + error: string | null + rowsAffected: u32 + lastInsertId: u64 + value: T +} +``` + + + An error message, if an error occurred during the operation. Otherwise, this + field is `null`. + + + + The number of rows affected by the operation, which is typically 1 for a + scalar query. + + + + When inserting a row, this field contains the ID of the last inserted row. + This is useful for tables with auto-incrementing primary keys. + + + + The scalar value returned from the query. + diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx new file mode 100644 index 00000000..39d33da5 --- /dev/null +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -0,0 +1,272 @@ +--- +title: "Neo4j APIs" +sidebarTitle: "Neo4j" +description: "Execute queries and mutations against a Neo4j database" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Neo4j APIs allow you to run queries and mutations against a Neo4j +database. + +## Import + +To begin, import the `neo4j` namespace from the SDK: + +```ts +import { neo4j } from "@hypermode/modus-sdk-as" +``` + +## Neo4j APIs + +{/* */} + +The APIs in the `neo4j` namespace are below, organized by category. + + + +### Functions + +#### executeQuery + +Executes a Cypher query on the Neo4j database. + +```ts +function executeQuery( + connection: string, + query: string, + parameters: Variables = new Variables(), + dbName: string = "neo4j", +): EagerResult +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + A Neo4j Cypher query to execute. + + + + The parameters to pass to the query. + + + + An optional database name to use. Defaults to "neo4j" if not provided. + + +### Types + +#### EagerResult + +The result of a Neo4j query. + +```ts +class EagerResult { + Keys: string[] + Records: Record[] +} +``` + + + The keys of the result. + + + + The records of the result. + + +#### Entity + +An abstract class representing possible entities in a Neo4j query result. + +```ts +abstract class Entity { + elementId: string + props: DynamicMap +} +``` + + + The ID of the entity. + + + + The properties of the entity. + + +#### Node + +A node in a Neo4j query result. + +```ts +class Node extends Entity { + elementId: string // from base class + props: DynamicMap // from base class + labels: string[] +} +``` + + + The ID of the node. + + + + The properties of the node. + + + + The labels of the node. + + +#### Path + +A path in a Neo4j query result. + +```ts +class Path { + nodes: Node[] + relationships: Relationship[] +} +``` + + + The nodes in the path. + + + + The relationships in the path. + + +#### Point2D + +A 2D point in a Neo4j query result. + +```ts +class Point2D { + x: f64 + y: f64 + spatialRefId: u32 +} +``` + + + The X coordinate of the point. + + + + The Y coordinate of the point. + + + + The spatial reference ID of the point. + + +#### Point3D + +A 3D point in a Neo4j query result. + +```ts +class Point3D { + x: f64 + y: f64 + z: f64 + spatialRefId: u32 +} +``` + + + The X coordinate of the point. + + + + The Y coordinate of the point. + + + + The Z coordinate of the point. + + + + The spatial reference ID of the point. + + +#### Record + +A record in a Neo4j query result. + +```ts +class Record { + keys: string[] + values: string[] + get(key: string): string + getValue(key: string): T + asMap(): Map +} +``` + + + The keys of the record. + + + + The values of the record. + + + + Get a value from a record at a given key as a JSON encoded string. + + + Usually, you should use `getValue(key)` instead of this method. + + + + + Get a value from a record at a given key and cast or decode it to a specific + type. + + + + Convert the record to a map of keys and JSON encoded string values. + + +#### Relationship + +A relationship in a Neo4j query result. + +```ts +class Relationship extends Entity { + elementId: string // from base class + props: DynamicMap // from base class + startElementId: string + endElementId: string + type: string +} +``` + + + The ID of the relationship. + + + + The properties of the relationship. + + + + The ID of the start node. + + + + The ID of the end node. + + + + The type of the relationship. + diff --git a/modus/sdk/assemblyscript/overview.mdx b/modus/sdk/assemblyscript/overview.mdx new file mode 100644 index 00000000..383d26bb --- /dev/null +++ b/modus/sdk/assemblyscript/overview.mdx @@ -0,0 +1,65 @@ +--- +title: "Modus AssemblyScript SDK" +sidebarTitle: "Overview" +description: "Learn how to use the Modus AssemblyScript SDK" +icon: "circle-info" +--- + +import SdkOverviewIntro from "/snippets/sdk-overview-intro.mdx" + + + +## Importing the APIs + +The Modus AssemblyScript SDK organizes its APIs into namespaces based on their +purpose. In your AssemblyScript code, you can import each namespace you'd like +to use like this: + +```ts +import { } from "@hypermode/modus-sdk-as" +``` + +## Available APIs + +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The following namespaces are available. They're grouped into categories below +for your convenience. Click on a namespace to view more information about its +APIs. + +### Client APIs + +| Namespace | Purpose | +| :--------------------- | :--------------------------------------------------------------------------------- | +| [`http`](./http) | Provides access to external HTTP endpoints, including REST APIs and other services | +| [`graphql`](./graphql) | Allows you to securely call and fetch data from any GraphQL endpoint | + +### Database APIs + +| Namespace | Purpose | +| :--------------------------- | :---------------------------------------------- | +| [`dgraph`](./dgraph) | Access and modify data in a Dgraph database | +| [`mysql`](./mysql) | Access and modify data in a MySQL database | +| [`neo4j`](./neo4j) | Access and modify data in a Neo4j database | +| [`postgresql`](./postgresql) | Access and modify data in a PostgreSQL database | + +### Inference APIs + +| Namespace | Purpose | +| :------------------- | :--------------------------------------------------------------------------------------------- | +| [`models`](./models) | Invoke AI models, including large language models, embedding models, and classification models | + +### Storage APIs + +| Namespace | Purpose | +| :----------------------------- | :--------------------------------------------------------- | +| [`collections`](./collections) | Provides integrated storage and vector search capabilities | + +### System APIs + +| Namespace | Purpose | +| :------------------------- | :------------------------------------------------------- | +| [`console`](./console) | Provides logging, assertion, and timing functions | +| [`localtime`](./localtime) | Allows you to access the user's local time and time zone | diff --git a/modus/sdk/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx similarity index 59% rename from modus/sdk/postgresql.mdx rename to modus/sdk/assemblyscript/postgresql.mdx index ec5f0c53..d6b46a71 100644 --- a/modus/sdk/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -1,38 +1,34 @@ --- -title: PostgreSQL +title: "PostgreSQL APIs" +sidebarTitle: "PostgreSQL" description: "Execute queries against a PostgreSQL database" +icon: "circle-small" +iconType: "solid" --- -The Modus PostgreSQL API allows you to run queries against PostgreSQL or any +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any PostgreSQL-compatible database platform. ## Import To begin, import the `postgresql` namespace from the SDK: - - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/postgresql -``` - -```ts AssemblyScript +```ts import { postgresql } from "@hypermode/modus-sdk-as" ``` - - ## PostgreSQL APIs {/* */} The APIs in the `postgresql` namespace are below, organized by category. - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - + ### Functions @@ -44,37 +40,39 @@ statements that don't return data. The `execute` function is for operations that don't return data. However, some - insert/update/delete operations may still return data, such as an identifier - for a newly inserted row. In these cases, you can use the `queryScalar` - function instead (for a single row's identifier), or the `query` function (for - multiple rows). + insert/update/delete operations may still return data. In these cases, you can + use the `queryScalar` or `query` functions instead. -```go -function postgresql.execute ( - connectionName: string, +```ts +function execute( + connection: string, statement: string, - params?: Params + params?: Params, ): Response ``` - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](/modus/app-manifest#connections). - SQL statement containing the query or mutation operation to execute. - - While it's possible to directly include parameter values into your SQL statement, it's - highly recommended to pass a [`Params`](#params) object instead. This can help to prevent - against injection attacks and other security vulnerabilities. - +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass a [`Params`](#params) object + instead. This can help to protect against injection attacks and other security + vulnerabilities. + + - Optional parameters to include with the query. + +Optional parameters to include with the query. See the details of the [`Params`](#params) object for more information. @@ -86,20 +84,24 @@ Execute a SQL statement against a PostgreSQL database, returning a set of rows. In the results, each row converts to an object of type `T`, with fields matching the column names. -```go -function postgresql.query( - connectionName: string, +```ts +function query( + connection: string, statement: string, params?: Params, ): QueryResponse ``` - - Type of object to use for the data returned from the query. This can be any type, including a custom - type defined in your project. It should match the shape of the row returned from the SQL query. + + +Type of object to use for the data returned from the query. This can be any +type, including a custom type defined in your project. It should match the shape +of the row returned from the SQL query. + + - - Define custom types in the app's source code. In AssemblyScript, create classes decorated with `@json`. +Define custom types in the app's source code. In AssemblyScript, create classes +decorated with `@json`. All types, including classes, base classes, and field types must be JSON serializable. You can also use built-in types such as strings, numbers, arrays, @@ -108,26 +110,31 @@ and maps. If working with PostgreSQL's `point` data type, you can use a [`Point`](#point) or [`Location`](#location) object to represent the data. - + + - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](/modus/app-manifest#connections). - SQL statement containing the query or mutation operation to execute. - - While it's possible to directly include parameter values into your SQL statement, it's highly - recommended to pass a [`Params`](#params) object instead. This can help to prevent against - injection attacks and other security vulnerabilities. - +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass a [`Params`](#params) object + instead. This can help to protect against injection attacks and other security + vulnerabilities. + + - Optional parameters to include with the query. + +Optional parameters to include with the query. See the details of the [`Params`](#params) object for more information. @@ -139,73 +146,108 @@ Execute a SQL statement against a PostgreSQL database, returning a single scalar value. For example, the result could be a count, sum, or average, or it could be an identifier. -```go -function postgresql.queryScalar ( - connectionName: string, +```ts +function queryScalar( + connection: string, statement: string, - params?: Params + params?: Params, ): ScalarResponse ``` - + Type of object to use for the data returned from the query. This should generally be a scalar data type, such as a number or string. It should match the type of the data returned from the SQL query. - + Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](/modus/app-manifest#connections). - SQL statement containing the query or mutation operation to execute. - - While it's possible to directly include parameter values into your SQL statement, it's highly - recommended to pass a [`Params`](#params) object instead. This can help to prevent against - injection attacks and other security vulnerabilities. - +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass a [`Params`](#params) object + instead. This can help to protect against injection attacks and other security + vulnerabilities. + + - Optional parameters to include with the query. + +Optional parameters to include with the query. See the details of the [`Params`](#params) object for more information. -### Objects +### Types -#### Params +#### Location -```go -class Params { - public push(value: any): void; - public toJSON(): string; +Represents a location on Earth, having `longitude` and `latitude` coordinates. + +Correctly serializes to and from PostgreSQL's point type, in (longitude, +latitude) order. + + + This class is identical to the [Point](#point) class, but uses different field + names. + + +```ts +class Location { + longitude: f64, + latitude: f64, } ``` + + The longitude coordinate of the location, in degrees. + + + + The latitude coordinate of the location, in degrees. + + +#### Params + A container for parameters to include with a SQL operation. To use this feature, create a new `Params` object and call the `push` method for each parameter you want to include. Then pass the object to the `execute`, `query`, or `queryScalar` function along with your SQL statement. +```ts +class Params { + push(value: T): void + toJSON(): string +} +``` + - Push a parameter value into the list included with the SQL operation. The sequence of calls to - `push` determines the order of the parameters in the SQL statement. This corresponds to the order - of the `?` placeholders or `$1`, `$2`, etc. - - The value of the parameter to include in the SQL operation. +Push a parameter value into the list included with the SQL operation. The +sequence of calls to `push` determines the order of the parameters in the SQL +statement. This corresponds to the order of the `?` placeholders or `$1`, `$2`, +etc. + + +{/* */} + + + +The value of the parameter to include in the SQL operation. The value can be of any type that's JSON serializable, including strings, numbers, boolean values, arrays, maps, and custom objects decorated with `@json`, as long as the database supports it. -{" "} - If working with PostgreSQL's `Point` data type, you can either pass separate parameters for the coordinates and use a `point()` function in the SQL @@ -214,6 +256,11 @@ numbers, boolean values, arrays, maps, and custom objects decorated with + +{/* */} + + + @@ -222,46 +269,58 @@ numbers, boolean values, arrays, maps, and custom objects decorated with typically don't need to call it directly. -#### Response +#### Point -```go -class Response { - error: string | null; - rowsAffected: u32; +Represents a point in 2D space, having `x` and `y` coordinates. Correctly +serializes to and from PostgreSQL's point type, in (x, y) order. + + + This class is identical to the [Location](#location) class, but uses different + field names. + + +```ts +class Point { + x: f64, + y: f64, } ``` -Represents the response from an [`execute`](#execute) operation. Also serves as -the base class for `QueryResponse` and `ScalarResponse`. - - - An error message, if an error occurred during the operation. Otherwise, this - field is `null`. + + The x coordinate of the point. - - The number of rows affected by the operation. + + The y coordinate of the point. #### QueryResponse -```go +Represents the response from a [`query`](#query) operation. + +```ts class QueryResponse { - error: string | null; - rowsAffected: u32; - rows: T[]; + error: string | null + rowsAffected: u32 + lastInsertId: u64 + rows: T[] } ``` -Represents the response from a [`query`](#query) operation. - An error message, if an error occurred during the operation. Otherwise, this field is `null`. - The number of rows affected by the operation. + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + This field is available for other database types, but isn't populated for + PostgreSQL. Instead, use `query` or `queryScalar` with a `RETURNING` clause to + get the last inserted ID. @@ -269,18 +328,19 @@ Represents the response from a [`query`](#query) operation. object has fields corresponding to the columns in the result set. -#### ScalarResponse +#### Response -```go -class ScalarResponse { - error: string | null; - rowsAffected: u32; - value: T; +Represents the response from an [`execute`](#execute) operation. Also serves as +the base class for `QueryResponse` and `ScalarResponse`. + +```ts +class Response { + error: string | null + rowsAffected: u32 + lastInsertId: u64 } ``` -Represents the response from a [`queryScalar`](#queryscalar) operation. - An error message, if an error occurred during the operation. Otherwise, this field is `null`. @@ -290,58 +350,41 @@ Represents the response from a [`queryScalar`](#queryscalar) operation. The number of rows affected by the operation. - - The scalar value returned from the query. + + This field is available for other database types, but isn't populated for + PostgreSQL. Instead, use `query` or `queryScalar` with a `RETURNING` clause to + get the last inserted ID. -#### Point +#### ScalarResponse -```go -class Point { - x: f64, - y: f64, +Represents the response from a [`queryScalar`](#queryscalar) operation. + +```ts +class ScalarResponse { + error: string | null + rowsAffected: u32 + lastInsertId: u64 + value: T } ``` -Represents a point in 2D space, having `x` and `y` coordinates. Correctly -serializes to and from PostgreSQL's point type, in (x, y) order. - - - This class is identical to the [Location](#location) class, but uses different - field names. - - - - The x coordinate of the point. + + An error message, if an error occurred during the operation. Otherwise, this + field is `null`. - - The y coordinate of the point. + + The number of rows affected by the operation, which is typically 1 for a + scalar query. -#### Location - -```go -class Location { - longitude: f64, - latitude: f64, -} -``` - -Represents a location on Earth, having `longitude` and `latitude` coordinates. - -Correctly serializes to and from PostgreSQL's point type, in (longitude, -latitude) order. - - - This class is identical to the [Point](#point) class, but uses different field - names. - - - - The longitude coordinate of the location, in degrees. + + This field is available for other database types, but isn't populated for + PostgreSQL. Instead, use `query` or `queryScalar` with a `RETURNING` clause to + get the last inserted ID. - - The latitude coordinate of the location, in degrees. + + The scalar value returned from the query. diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx new file mode 100644 index 00000000..58232cda --- /dev/null +++ b/modus/sdk/go/collections.mdx @@ -0,0 +1,718 @@ +--- +title: "Collections APIs" +sidebarTitle: "Collections" +description: "Add storage and vector search capabilities to your functions." +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Collection APIs allow you to add vector search within your functions. + +## Import + +To begin, import the `collections` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/collections" +``` + +## Collections APIs + +{/* */} + +The APIs in the `collections` package are below, organized by category. + + + +### Mutation Functions + +#### Upsert + +Inserts or updates an item in a collection. + + + If the item already exists, the function overwrites the previous value. If + not, it creates a new one. + + +```go +func Upsert( + collection string, + key *string, + text string, + labels []string, + opts ...NamespaceOption +) (*CollectionMutationResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The unique identifier for the item in the namespace. If `nil`, the function + generates a unique identifier. + + + + The text of the item to add to the collection. + + + + An optional slice of labels to associate with the item. + + + + Associates the item with a specific namespace. Defaults to an empty namespace + if not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### UpsertBatch + +Inserts or updates a batch of items into a collection. + + + If an item with the same key already exists, the original text is overwritten + with the new text. + + +```go +func UpsertBatch( + collection string, + keys []string, + texts []string, + labelsArr [][]string, + opts ...NamespaceOption +) (*CollectionMutationResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + Slice of keys for the item to add to the collection. If you pass `nil` for any + key, Hypermode assigns a new UUID as the key for the item. + + + + Slice of texts for the items to add to the collection. + + + + An optional slice of slices of labels to associate with the items. + + + + Associates the item with a specific namespace. Defaults to an empty namespace + if not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### Remove + +Removes an item from the collection. + +```go +func Remove( + collection string, + key string, + opts ...NamespaceOption +) (*CollectionMutationResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The key of the item to delete from the collection. + + + + The namespace to remove the item from. Defaults to the default namespace if + not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +### Search and Retrieval Functions + +#### ComputeDistance + +Computes distance between two keys in a collection using a search method's +embedder. + +```go +func ComputeDistance( + collection string, + searchMethod string, + key1 string, + key2 string, + opts ...NamespaceOption +) (*CollectionSearchResultObject, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The search method used to calculate embedding for key's texts. + + + + Keys to compute similarity on. + + + + The namespace to search the items from. Defaults to the default namespace if + not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### NnClassify + +Classify an item in the collection using previous vectors' labels. + +```go +func NnClassify( + collection string, + searchMethod string, + text string, + opts ...NamespaceOption +) (*CollectionClassificationResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The search method used to calculate embedding for text & search against. + + + + The text to compute natural language search on. + + + + The namespace to search the items from. Defaults to the default namespace if + not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### GetLabels + +Get the labels for an item in a collection. + +```go +func GetLabels( + collection string, + key string, + opts ...NamespaceOption +) ([]string, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The key of the item to retrieve. + + + + The namespace to get the item from. Defaults to the default namespace if not + provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### GetNamespaces + +Get all namespaces in a collection. + +```go +func GetNamespaces(collection string) ([]string, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + +#### GetText + +Gets an item's text from a collection, give the item's key. + +```go +func GetText( + collection string, + key string, + opts ...NamespaceOption +) (string, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The key of the item to retrieve. + + + + The namespace to get the item from. Defaults to the default namespace if not + provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### GetTexts + +Get all items from a collection. The result is a map of key to text for all +items in the collection. + +```go +func GetTexts( + collection string, + opts ...NamespaceOption +) (map[string]string, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The namespace to get the items from. Defaults to the default namespace if not + provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### GetVector + +Get the vector for an item in a collection. + +```go +func GetVector( + collection string, + searchMethod string, + key string, + opts ...NamespaceOption +) ([]float32, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The search method used to calculate embedding for key's texts. + + + + The key of the item to retrieve. + + + + The namespace to get the item from. Defaults to the default namespace if not + provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +#### Search + +Perform a natural language search on items within a collection. This method is +useful for finding items that match a search query based on semantic meaning. + + + Modus uses the same embedder for both inserting text into the collection, and + for the text used when searching the collection. + + +```go +func Search( + collection string, + searchMethod string, + text string, + opts ...SearchOption +) (*CollectionSearchResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The search method used to calculate embedding for text & search against. + + + + The text to compute natural language search on. + + + + Additional options for the search: + +- `collections.WithLimit(limit int)`: The number of result objects to return. +- `collections.WithReturnText(returnText bool)`: A flag to return the texts in + the response. +- `collections.WithNamespaces(namespaces []string)`: A list of namespaces to + search the item from. Defaults to the default namespace if not provided. + + + +#### SearchByVector + +Perform a vector-based search on a collection, which is helpful for scenarios +requiring precise similarity calculations between pre-computed embeddings. + + + Modus uses the same embedder for both inserting text into the collection, and + for the vector used when searching the collection. + + +```go +func SearchByVector( + collection string, + searchMethod string, + vector []float32, + opts ...SearchOption +) (*CollectionSearchResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The search method used to calculate embedding for vector & search against. + + + + The vector to compute search on. + + + + Additional options for the search: + +- `collections.WithLimit(limit int)`: The number of result objects to return. +- `collections.WithReturnText(returnText bool)`: A flag to return the texts in + the response. +- `collections.WithNamespaces(namespaces []string)`: A list of namespaces to + search the item from. Defaults to the default namespace if not provided. + + + +### Maintenance Functions + +#### RecomputeSearchMethod + +Recalculates the embeddings for all items in a collection. It can be +resource-intensive, use it when necessary, for example after you have updated +the method for embedding calculation and want to re-compute the embeddings for +existing data in the collection. + +```go +func RecomputeSearchMethod( + collection string, + searchMethod string, + opts ...NamespaceOption +) (*SearchMethodMutationResult, error) +``` + + + Name of the collection, as [defined in the + manifest](/modus/app-manifest#collections). + + + + The search method to recompute embeddings for. + + + + The namespace to use. Defaults to the default namespace if not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + + + +### Types + +#### CollectionClassificationLabelObject + +Represents a classification label. + +```go +type CollectionClassificationLabelObject struct { + Label string + Confidence float64 +} +``` + + + The classification label. + + + + The confidence score of the classification label. + + +#### CollectionClassificationResult + +Represents the result of a classification operation on a collection. + +```go +type CollectionClassificationResult struct { + Collection string + Status string + Error string + SearchMethod string + LabelsResult []*CollectionClassificationLabelObject + Cluster []*CollectionClassificationResultObject +} +``` + + + Name of the collection. + + + + The status of the operation. + + + + Error message, if any. + + + + The search method used in the operation. + + + + The classification labels. + + + + The classification results. + + +#### CollectionClassificationResultObject + +Represents an object in the classification results. + +```go +type CollectionClassificationResultObject struct { + Key string + Labels []string + Distance float64 + Score float64 +} +``` + + + The key of the item classified. + + + + The classification labels. + + + + The distance of the item from the classification labels. + + + + The similarity score of the item classified. + + +#### CollectionMutationResult + +Represents the result of a mutation operation on a collection. + +```go +type CollectionMutationResult struct { + Collection string + Status string + Error string + Operation string + Keys []string +} +``` + + + Name of the collection. + + + + The status of the operation. + + + + Error message, if any. + + + + The operation performed. + + + + The keys of the items affected by the operation. + + +#### CollectionSearchResult + +Represents the result of a search operation on a collection. + +```go +type CollectionSearchResult struct { + Collection string + Status string + Error string + SearchMethod string + Objects []*CollectionSearchResultObject +} +``` + + + Name of the collection. + + + + The status of the operation. + + + + Error message, if any. + + + + The search method used in the operation. + + + + The search results. + + +#### CollectionSearchResultObject + +Represents an object in the search results. + +```go +type CollectionSearchResultObject struct { + Namespace string + Key string + Text string + Labels []string + Distance float64 + Score float64 +} +``` + + + The namespace of the item found as part of the search. + + + + The key of the item found as part of the search. + + + + The text of the item found as part of the search. + + + + The distance of the item from the search text. + + + + The similarity score of the item found, as it pertains to the search. + + +#### CollectionStatus + +The status of a collection operation. + +```go +type CollectionStatus = string + +const ( + Success CollectionStatus = "success" + Error CollectionStatus = "error" +) +``` + +The operation was successful. + +The operation encountered an error. + +#### SearchMethodMutationResult + +Represents the result of a mutation operation on a search method. + +```go +type SearchMethodMutationResult struct { + Collection string + Status string + Error string + Operation string + SearchMethod string +} +``` + + + Name of the collection. + + + + The status of the operation. + + + + Error message, if any. + + + + The operation performed. + + + + The search method affected by the operation. + diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx new file mode 100644 index 00000000..65b64ee4 --- /dev/null +++ b/modus/sdk/go/console.mdx @@ -0,0 +1,258 @@ +--- +title: "Console APIs" +sidebarTitle: "Console" +description: "Capture errors and debugging information in your functions" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Console APIs allow you to capture information from your functions, +such as errors and other information that can help you debug your functions. + + + +In addition to the Console APIs, you can also use any standard Go function that +emits output to `stdout` or `stderr`. The output from these functions are +available in the runtime logs. + +For example, you may use: + +- `fmt.Println` to write to informational messages to the logs +- `fmt.Fprintf(os.Stderr, ...)` to write error messages to the logs + +You may also _return_ `error` objects from your function, whose messages get +captured and returned in the GraphQL response. + + + +## Import + +To begin, import the `console` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/console" +``` + +## Console APIs + +{/* */} + +The APIs in the `console` package are below, organized by category. + + + +### Assertion Functions + +#### Assert + +Asserts that a condition is true, and logs an error if it's not. + +```go +func Assert(condition bool, message string) +``` + + + The boolean condition to assert. + + + + An error message to log, if the assertion is false. + + +### Logging Functions + + + For Go, typically you use these logging APIs when you need detailed control of + the logging level, or when you need to log multi-line messages as a single log + entry. Otherwise, you can use the standard Go functions from the `fmt` package + to emit messages to `stdout` or `stderr`. + + +#### Log + +Generate a log message, with no particular logging level. + +```go +func Log(message string) +``` + + + A message you want to log. + + +#### Logf + +Generate a message using Go format specifiers and logs the message, with no +particular logging level. + +```go +func Logf(message string, args ...any) +``` + + + A message you want to log. + + + + Arguments that correspond to the format specifiers in the message. + + +#### Debug + +Generate a log message with the "debug" logging level. + +```go +func Debug(message string) +``` + + + A debug message you want to log. + + +#### Debugf + +Generate a message using Go format specifiers and logs the message with the +"debug" logging level. + +```go +func Debugf(message string, args ...any) +``` + + + A debug message you want to log. + + + + Arguments that correspond to the format specifiers in the message. + + +#### Info + +Generate a log message with the "info" logging level. + +```go +func Info(message string) +``` + + + An informational message you want to log. + + +#### Infof + +Generate a message using Go format specifiers and logs the message with the +"info" logging level. + +```go +func Infof(message string, args ...any) +``` + + + An informational message you want to log. + + + + Arguments that correspond to the format specifiers in the message. + + +#### Warn + +Generate a log message with the "warning" logging level. + +```go +func Warn(message string) +``` + + + A warning message you want to log. + + +#### Warnf + +Generate a message using Go format specifiers and logs the message with the +"warning" logging level. + +```go +func Warnf(message string, args ...any) +``` + + + A warning message you want to log. + + + + Arguments that correspond to the format specifiers in the message. + + +#### Error + +Generate a log message with the "error" logging level. + +```go +func Error(message string) +``` + + + An error message you want to log. + + +#### Errorf + +Generate a message using Go format specifiers and logs the message with the +"error" logging level. + +```go +func Errorf(message string, args ...any) +``` + + + An error message you want to log. + + + + Arguments that correspond to the format specifiers in the message. + + +### Timing Functions + +#### Time + +Starts a new timer using the specified label. + +```go +func Time(label ...string) +``` + + + An optional label for the timer. + + +#### TimeLog + +Logs the current value of a timer previously started with `console.Time`. + +```go +func TimeLog(label string) +``` + + + An optional label for the timer. + + +#### TimeEnd + +Logs the current value of a timer previously started with `console.Time`, and +discards the timer. + +```go +func TimeEnd(label string) +``` + + + An optional label for the timer. + diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx new file mode 100644 index 00000000..b0cd9140 --- /dev/null +++ b/modus/sdk/go/dgraph.mdx @@ -0,0 +1,172 @@ +--- +title: "Dgraph APIs" +sidebarTitle: "Dgraph" +description: "Execute queries and mutations against a Dgraph database" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph +database. + +## Import + +To begin, import the `dgraph` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/dgraph" +``` + +## Dgraph APIs + +{/* */} + +The APIs in the `dgraph` package are below, organized by category. + + + +### Functions + +#### AlterSchema + +Alter the schema of a Dgraph database. + +```go +func AlterSchema(connection, schema string) error +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + The schema to apply to the Dgraph database. + + +#### DropAll + +Drop all data from a Dgraph database. + +```go +func DropAll(connection string) error +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + +#### DropAttr + +Drop an attribute from a Dgraph schema. + +```go +func DropAttr(connection, attr string) error +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + The attribute to drop from the Dgraph schema. + + +#### Execute + +Execute a Dgraph query or mutation using a Dgraph Request object. + +```go +func Execute(connection string, request *Request) (*Response, error) +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + A pointer to a Dgraph [`Request`](#request) object, describing the query or + mutation to execute. + + +### Types + +#### Mutation + +A Dgraph mutation object, used to execute mutations. + +```go +type Mutation struct { + SetJson string + DelJson string + SetNquads string + DelNquads string + Condition string +} +``` + + + A JSON string representing the data to set in the mutation. + + + + A JSON string representing the data to delete in the mutation. + + + + A string representing the data to set in the mutation in NQuads format. + + + + A string representing the data to delete in the mutation in NQuads format. + + + + A string representing the condition query for the mutation. + + +#### Query + +A Dgraph query object, used to execute queries. + +```go +type Query struct { + Query string + Variables map[string]string +} +``` + + + The DQL query to execute. + + + + A map of query variables. + + +#### Request + +A Dgraph request object, used to execute queries and mutations. + +```go +type Request struct { + Query *Query + Mutations []*Mutation +} +``` + + + A pointer to a Dgraph [`query`](#query) object. + + + + An slice of pointers to Dgraph [`mutation`](#mutation) objects. + diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx new file mode 100644 index 00000000..1d80466b --- /dev/null +++ b/modus/sdk/go/graphql.mdx @@ -0,0 +1,167 @@ +--- +title: "GraphQL APIs" +sidebarTitle: "GraphQL" +description: "Access external GraphQL data sources from your functions" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus GraphQL APIs allow you to securely call and fetch data from any +GraphQL endpoint. + +## Import + +To begin, import the `graphql` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/graphql" +``` + +## GraphQL APIs + +{/* */} + +The APIs in the `graphql` package are below, organized by category. + + + +### Functions + +#### Execute + +Execute a GraphQL statement to call a query or apply mutation against a GraphQL +endpoint. + +```go +Execute[T any]( + connection, + statement string, + variables map[string]any +) (*Response[T], error) +``` + + + +Type of object to use for the data returned from the query. This can be any +type, including a custom type defined in your project. It should match the shape +of the data returned from the GraphQL query. + + + Define custom types in the project's source code. All types must be JSON + serializable. You can also use built-in types such as strings, numbers, + slices, and maps. + + + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connection). + + + + GraphQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your GraphQL + statement, it's highly recommended to pass a variables map instead. This can + help to prevent against injection attacks and other security vulnerabilities. + + + + + + +Optional variables to include with the query. + +The key should be the name of the GraphQL variable. The value can be of any type +that's JSON serializable, including strings, numbers, boolean values, slices, +maps, and custom structs. + + + +### Types + +#### Response + +```go +type Response[T any] struct { + Errors []ErrorResult + Data *T +} +``` + +A response object from the GraphQL query. + +Either `Errors` or `Data` is present, depending on the result of the query. + + + +An slice of errors incurred as part of your GraphQL request, if any. + +Each error in the slice is an [`ErrorResult`](#errorresult) object. If there are +no errors, this field is `nil`. + + + + + +The resulting data selected by the GraphQL operation. + +The data is a pointer to an object the type specified in the call to the +`Execute` function. If data is absent due to errors, this field is `nil`. + + + +#### ErrorResult + +```go +type ErrorResult struct { + Message string + Locations []CodeLocation + Path []string +} +``` + +The details of an error incurred as part of a GraphQL operation. + + + Description of the error incurred. + + + + +Path to the area of the GraphQL statement related to the error. + +Each item in the slice represents a segment of the path. + + + + + An slice of [`CodeLocation`](#codelocation) objects that point to the specific + location of the error in the GraphQL statement. + + +#### CodeLocation + +```go +type CodeLocation struct { + Line uint32 + Column uint32 +} +``` + +The location of specific code within a GraphQL statement. + + + Line number within the GraphQL statement for the code. + + + + Column number within the GraphQL statement for the code. + diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx new file mode 100644 index 00000000..3da84c6f --- /dev/null +++ b/modus/sdk/go/http.mdx @@ -0,0 +1,450 @@ +--- +title: "HTTP APIs" +sidebarTitle: "HTTP" +description: "Access external HTTP endpoints from your functions" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus HTTP APIs allow you to securely call and fetch data from an HTTP +endpoint. It's similar to the HTTP +[`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API used in +JavaScript, but with some modifications to work with Modus. + +In a future version of Modus, we'll support Go's standard `net/http` package for +making HTTP requests. However, that's currently not supported due to technical +limitations. + + + +As a security measure, you can only call HTTP endpoints that you +[defined in your app's manifest](/modus/app-manifest#connections). Any attempt +to access an arbitrary URL, for a connection not defined in your app's manifest, +results in an error. + +Additionally, you should use placeholders for connection secrets in the +manifest, rather than hardcoding them in your functions. Enter the values for +each connections' secrets via environment variables or the Hypermode UI. This +ensures that your secrets are securely stored, aren't committed to your +repository, and aren't visible or accessible from your functions code. + + + +## Import + +To begin, import the `http` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/http" +``` + +## HTTP APIs + +{/* */} + +The APIs in the `http` package are below, organized by category. + + + +### Functions + +#### Fetch + +Invoke an HTTP endpoint to retrieve data or trigger external action. + +Returns a [`Response`](#response) object with the HTTP response data. + +```go +func Fetch[T *Request | string]( + requestOrUrl T, + options ...*RequestOptions +) (*Response, error) +``` + + + +Either a URL `string` or a pointer to a [`Request`](#request) object, describing +the HTTP request to make. + +If a `string`, the operation uses the `GET` HTTP method with no headers other +than those defined in the manifest entry of the connection. + + + Each request must match to a connection entry in the manifest, using the + `baseUrl` field. The request URL passed to the `Fetch` function (or via a + `Request` object) must start with the manifest entry's `baseUrl` value to + match. + + + + + + An optional pointer to a [`RequestOptions`](#requestoptions) object with + additional options for the request, such as the HTTP method, headers, and + body. + + +#### NewContent + +Creates a new [`Content`](#content) object from the given `value`, and returns a +pointer to it. + +```go +func NewContent(value any) *Content +``` + + + +The value to create the `Content` object from. Must be one of the following +types: + +- A [`Content`](#content) object, or a pointer to one. +- A `[]byte` of binary content, or a pointer to one. +- A `string` of text content. + + + +#### NewHeaders + +Creates a new [`Headers`](#headers) object from the given `value`, and returns a +pointer to it. + +```go +func NewHeaders[T [][]string | map[string]string | map[string][]string]( + value T +) *Headers +``` + + + +The value object to create the [`Headers`](#headers) object from. Must be one of +the following types: + +- A `[][]string`, where each inner slice contains a header name and value. +- A `map[string]string`, where the keys are header names and the values are + header values. +- A `map[string][]string`, where the keys are header names and the values are + slices of header values. + + + +#### NewRequest + +Creates a new [`Request`](#request) object with the given `url` and `options`, +and returns a pointer to it. + +```go +func NewRequest(url string, options ...*RequestOptions) *Request +``` + + + The fully qualified URL of the request, including the protocol. For example, + `"https://example.com"`. + + + + An optional pointer to a [`RequestOptions`](#requestoptions) object that's + used to set the HTTP method, headers, and body if needed. + + +### Types + +#### Content + +Represents content used in the body of an HTTP request or response. + + + Use the [`NewContent`](#newcontent) function to create a new `Content` object. + + +```go +type Content struct { + // no exported fields +} + +// methods +func (*Content) Bytes() []byte +func (*Content) Text() string +func (*Content) JSON(result any) error +``` + + + Returns the binary content as a byte slice. + + + + Interprets the content as a UTF-8 encoded string, and returns it as a `string` + value. + + + + +Interprets the content as a UTF-8 encoded string containing JSON, and attempts +to deserialize it into the `result` provided. + +Pass the `result` as a pointer to an object matching the shape of the JSON. For +example: + +```go +var data MyData +if err := content.JSON(&data); err != nil { + // handle error +} +``` + + + +#### Header + +Represents an HTTP request or response header. + +```go +type Header struct { + Name string + Values []string +} +``` + + + The name of the header. + + + + An slice of values for the header. Typically a header has a single value, but + some headers can have multiple values. + + +#### Headers + +Represents a collection of HTTP headers. + + + Use the [`NewHeaders`](#newheaders) function to create a new `Headers` object. + + +```go +type Headers struct { + // no exported fields +} + +// methods +func (*Headers) Append(name, value string) +func (*Headers) Entries() [][]string +func (*Headers) Get(name string) *string +``` + + + Appends a new header with the given `name` and `value` to the collection. + + + + Returns a `[][]string`, where each inner slice contains a header name and + value. + + + + Returns the value of the header with the given `name`, or `nil` if the header + doesn't exist. If there are multiple values for the header, this function + concatenates them with a comma to form a single string. + + +#### Request + +Represents an HTTP request to make. + + + Use the [`NewRequest`](#newrequest) function to create a new `Request` object. + + +```go +type Request struct { + Url string + Method string + Headers *Headers + Body []byte +} + +// methods +func (*Request) Clone(options ...*RequestOptions) *Request +func (*Request) Bytes() []byte +func (*Request) Text() string +func (*Request) JSON(result any) error +``` + + + The fully qualified URL of the request, including the protocol. For example, + `"https://example.com"`. + + + + The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or + `"DELETE"`. + + + + The HTTP headers of the request, as a pointer to a [`Headers`](#headers) + object. + + + + +The raw binary content data of the request body. + + + The request body isn't normally read directly. Instead, use the `Bytes`, + `Text`, or `JSON` methods. + + + + + + Clones the `Request` object, applies the `options` to the new object, and + returns it. + + + + Returns the binary content of the request body as a byte slice. + + + + Interprets the content of the request body as a UTF-8 encoded string, and + returns it as a `string` value. + + + + +Interprets the content of the request body as a UTF-8 encoded string containing +JSON, and attempts to deserialize it into the `result` provided. + +Pass the `result` as a pointer to an object matching the shape of the JSON. For +example: + +```go +var data MyData +if err := request.JSON(&data); err != nil { + // handle error +} +``` + + + +#### RequestOptions + +Options for the HTTP request. + +```go +type RequestOptions struct { + Method string + Headers any + Body any +} +``` + + + The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or + `"DELETE"`. If empty, the request uses the `GET` method. + + + + +The HTTP headers of the request, which must be of one of the following types: + +- A [`Headers`](#headers) object, or a pointer to one. +- A `[][]string`, where each inner slice contains a header name and value. +- A `map[string]string`, where the keys are header names and the values are + header values. +- A `map[string][]string`, where the keys are header names and the values are + slices of header values. + + + + + +Content to pass in the request body. Must be one of the following types: + +- A [`Content`](#content) object, or a pointer to one. +- A `[]byte` of binary content, or a pointer to one. +- A `string` of text content. +- `nil` if there is no body to pass. + + + It's generally recommended to supply a `Content-Type` header for any requests + that have a body. + + + + +#### Response + +Represents the response received from the HTTP server. + +```go +type Response struct { + Status uint16 + StatusText string + Headers *Headers + Body []byte +} + +// methods +func (*Response) Ok() bool +func (*Response) Bytes() []byte +func (*Response) Text() string +func (*Response) JSON(result any) error +``` + + + The HTTP response status code, such as `200` for success. + + + + The HTTP response status text associated with the status code, such as `"OK"` + for success. + + + + The HTTP headers received with the response, as a pointer to a + [`Headers`](#headers) object. + + + + +The raw binary content data of the response body. + + + The response body isn't normally read directly. Instead, use the `Bytes`, + `Text`, or `JSON` methods. + + + + + + Returns the binary content of the response body as a byte slice. + + + + Interprets the content of the response body as a UTF-8 encoded string, and + returns it as a `string` value. + + + + +Interprets the content of the response body as a UTF-8 encoded string containing +JSON, and attempts to deserialize it into the `result` provided. + +Pass the `result` as a pointer to an object matching the shape of the JSON. For +example: + +```go +var data MyData +if err := response.JSON(&data); err != nil { + // handle error +} +``` + + diff --git a/modus/sdk/go/localtime.mdx b/modus/sdk/go/localtime.mdx new file mode 100644 index 00000000..f1c9bc23 --- /dev/null +++ b/modus/sdk/go/localtime.mdx @@ -0,0 +1,150 @@ +--- +title: "Local Time APIs" +sidebarTitle: "Local Time" +description: "Access the user's local time and time zone in your functions" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Local Time APIs allow you to access the user's local time and time +zone from your functions. + +## Import + +To begin, import the `localtime` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/localtime" +``` + +{/* */} + +## Local Time APIs + +The APIs in the `localtime` package are below. + +All time zones use the IANA time zone database format. For example, +`"America/New_York"`. You can find a list of valid time zones +[here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + + + +{/* */} + +For APIs that work with the user's local time, the time zone is determined in +the following order of precedence: + +- If the `X-Time-Zone` header is present in the request, the time zone is set to + the value of the header. +- If the `TZ` environment variable is set on the host, the time zone is set to + the value of the variable. +- Otherwise, the time zone is set to the host's local time zone. + +{/* */} + + + + + +When working locally with `modus dev`, Modus uses the host's local time zone by +default. You can override this by setting the `TZ` environment variable in your +`.env.local` file. + + + + + +In a browser-based web app, you can get the user's time zone with the following +JavaScript code: + +```js +const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone +``` + +Assign that value to a `"X-Time-Zone"` request header when calling Modus, to use +it for all local time calculations. + + + + + +In many cases, you can use Go's built-in time support: + +```go +// to get the current time in UTC +now := time.Now().UTC() + +// if you need a string +s := now.Format(time.RFC3339) +``` + + + + + +Due to Go's WASM implementation, the standard `time.Now()` function always +returns the UTC time, not the user's local time like it usually does in Go. If +you need the user's local time, use `localtime.Now()` instead. + + + + + +### Functions + +#### GetLocation + +Returns a pointer to a Go `time.Location` object for a specific time zone. +Errors if the time zone provided is invalid. + +```go +func GetLocation(tz string) (*time.Location, error) +``` + +#### GetTimeZone + +Returns the user's time zone in IANA format. + +```go +func GetTimeZone() string +``` + +#### IsValidTimeZone + +Determines whether the specified time zone is a valid IANA time zone and +recognized by the system as such. + +```go +func IsValidTimeZone(tz string) bool +``` + + + An IANA time zone identifier, such as `"America/New_York"`. + + +#### Now + +Returns the current time as a `time.Time` object, with the location set to the +user's local time zone. Errors if the time zone passed to the host is invalid. + +```go +func Now() (time.Time, error) +``` + +#### NowInZone + +Returns the current time as a `time.Time` object, with the location set to a +specific time zone. Errors if the time zone provided is invalid. + +```go +func NowInZone(tz string) (time.Time, error) +``` + + + An IANA time zone identifier, such as `"America/New_York"`. + diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx new file mode 100644 index 00000000..81442e8d --- /dev/null +++ b/modus/sdk/go/models.mdx @@ -0,0 +1,195 @@ +--- +title: "AI Model APIs" +sidebarTitle: "Models" +description: "Invoke AI models from your functions" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Models APIs allow you to invoke AI models directly from your +functions, irrespective of the model's host. + +Since many models have unique interfaces, the design of the Models APIs are +extremely flexible. An interface and common base type forms the core of the +APIs, which extends to conform to any model's required schema. + +The SDK contains both the base types and pre-defined implementations for many +commonly used models. You can either use one of the pre-defined model types, or +can create custom types for any model you like, by following the same pattern as +implemented in the pre-defined models. + + +For your reference, several complete examples for using the Models APIs are available in +[Model Invoking](/modus/model-invoking). + +Each example demonstrates using different types of AI models for different +purposes. However, the Models interface isn't limited to these purposes. You can +use it for any task that an AI model can perform. + + + +## Import + +To begin, import the `models` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/models" +``` + +You'll also need to import one or more packages for the model you are working +with. For example: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai" +``` + +If you would like to request a new model, please +[open an issue](https://github.com/hypermodeinc/modus/issues). You can also send +a pull request, if you'd like to contribute a new model yourself. + +## Models APIs + +{/* */} + +The APIs in the `models` package are below, organized by category. + + + +### Functions + +#### GetModel + +Get a model instance by name and type. + +```go +func GetModel[TModel](modelName string) (*TModel, error) +``` + + + The type of model to return. This can be any struct that implements the + `Model` interface. + + + + The name of the model to retrieve. This must match the name of a model defined + in your project's manifest file. + + +### Types + +#### Model + +The interface that all Modus models must implement. + +```go +type Model[TIn, TOut any] interface { + Info() *ModelInfo + Invoke(input *TIn) (*TOut, error) +} +``` + + + The type of the input data for the model. This can be any type, including a + custom type defined in your project. It should match the shape of the data + expected by the model. It's usually a struct. + + + + The type of the output data from the model. This can be any type, including a + custom type defined in your project. It should match the shape of the data + returned by the model. It's usually a struct. + + + + Returns information about the model set by the Modus Runtime when creating the + instance. See the [`ModelInfo`](#modelinfo) object for more information. + + + + Invokes the model with input data and returns the output data. + + +#### ModelBase + +The base type for all models that Modus functions can invoke. + + + If you are implementing a custom model, you'll need to create a type alias + based on this struct. You'll also need structs to represent the input and + output types for your model. See the implementations of the pre-defined models + in the Modus GitHub repository for examples. + + +```go +type ModelBase[TIn, TOut any] struct { + Debug bool +} + +// methods +func (ModelBase[TIn, TOut]) Info() *ModelInfo +func (ModelBase[TIn, TOut]) Invoke(input *TIn) (*TOut, error) +``` + + + The type of the input data for the model. This can be any type, including a + custom type defined in your project. It should match the shape of the data + expected by the model. It's usually a struct. + + + + The type of the output data from the model. This can be any type, including a + custom type defined in your project. It should match the shape of the data + returned by the model. It's usually a struct. + + + + A flag to enable debug mode for the model. When enabled, Modus automatically + logs the full request and response data to the console. Implementations can + also use this flag to enable additional debug logging. Defaults to `false`. + + + + Returns information about the model set by the Modus Runtime when creating the + instance. See the [`ModelInfo`](#modelinfo) object for more information. + + + + Invokes the model with input data and returns the output data. + + +#### ModelInfo + +Information about a model that's used to construct a `Model` instance. It's also +available from a method on the `Model` interface. + + + +This struct relays information from the Modus runtime to the model +implementation. Generally, you don't need to create `ModelInfo` instances +directly. + +However, if you are implementing a custom model, you may wish to use a field +from this struct, such as `FullName`, for model providers that require the model +name in the input request body. + + + +```go +type ModelInfo struct { + Name string + FullName string +} +``` + + + The name of the model from the app manifest. + + + + The full name or identifier of the model, as defined by the model provider. + diff --git a/modus/sdk/go/mysql.mdx b/modus/sdk/go/mysql.mdx new file mode 100644 index 00000000..5a44818e --- /dev/null +++ b/modus/sdk/go/mysql.mdx @@ -0,0 +1,285 @@ +--- +title: "MySQL APIs" +sidebarTitle: "MySQL" +description: "Execute queries against a MySQL database" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus MySQL APIs allow you to run queries against MySQL or any +MySQL-compatible database platform. + +## Import + +To begin, import the `mysql` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/mysql" +``` + +## MySQL APIs + +{/* */} + +The APIs in the `mysql` package are below, organized by category. + + + +### Functions + +#### Execute + +Execute a SQL statement against a MySQL database, without any data returned. Use +this for insert, update, or delete operations, or for other SQL statements that +don't return data. + + + The `Execute` function is for operations that don't return data. However, some + insert/update/delete operations may still return data. In these cases, you can + use the `QueryScalar` or `Query` functions instead. + + +```go +func Execute(connection, statement string, params ...any) (*db.Response, error) +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass parameters as arguments instead. + This can help to protect injection attacks and other security vulnerabilities. + + + + + + Optional parameters to include with the query. + + +#### Query + +Execute a SQL statement against a MySQL database, returning a set of rows. In +the results, each row converts to an object of type `T`, with fields matching +the column names. + +```go +func Query[T any](connection, statement string, params ...any) (*db.QueryResponse[T], error) +``` + + + +Type of object to use for the data returned from the query. This can be any +type, including a custom type defined in your project. It should match the shape +of the row returned from the SQL query. + + + +Define custom types in the project's source code. All types must be JSON +serializable. You can also use built-in types such as strings, numbers, slices, +and maps. + +If working with MySQL's `point` data type, you can use a [`Point`](#point) or +[`Location`](#location) object to represent the data. + + + + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass parameters as arguments instead. + This can help to protect injection attacks and other security vulnerabilities. + + + + + + Optional parameters to include with the query. + + +#### QueryScalar + +Execute a SQL statement against a MySQL database, returning a single scalar +value. For example, the result could be a count, sum, or average, or it could be +an identifier. + +```go +func QueryScalar[T any](connection, statement string, params ...any) (*db.ScalarResponse[T], error) +``` + + + Type of object to use for the data returned from the query. This should + generally be a scalar data type, such as a number or string. It should match + the type of the data returned from the SQL query. + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass parameters as arguments instead. + This can help to protect injection attacks and other security vulnerabilities. + + + + + + Optional parameters to include with the query. + + +### Types + +#### Location + +Represents a location on Earth, having `Longitude` and `Latitude` coordinates. + +Correctly serializes to and from MySQL's point type, in (longitude, latitude) +order. + + + This struct is identical to the [Point](#point) struct, but uses different + field names. + + +```go +type Location struct { + Longitude float64 + Latitude float64 +} +``` + + + The longitude coordinate of the location, in degrees. + + + + The latitude coordinate of the location, in degrees. + + +#### Point + +Represents a point in 2D space, having `X` and `Y` coordinates. Correctly +serializes to and from MySQL's point type, in (x, y) order. + + + This struct is identical to the [Location](#location) struct, but uses + different field names. + + +```go +type Point struct { + X float64 + Y float64 +} +``` + + + The X coordinate of the point. + + + + The Y coordinate of the point. + + +#### QueryResponse + +Represents the response from a [`Query`](#query) operation. + +```go +type QueryResponse[T any] struct { + RowsAffected uint32 + LastInsertId uint64 + Rows []T +} +``` + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + When inserting a row, this field contains the ID of the last inserted row. + This is useful for tables with auto-incrementing primary keys. + + + + An slice of objects, each representing a row returned from the query. Each + object has fields corresponding to the columns in the result set. + + +#### Response + +Represents the response from an [`Execute`](#execute) operation. + +```go +type Response struct { + RowsAffected uint32 + LastInsertId uint64 +} +``` + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + When inserting a row, this field contains the ID of the last inserted row. + This is useful for tables with auto-incrementing primary keys. + + +#### ScalarResponse + +Represents the response from a [`QueryScalar`](#queryscalar) operation. + +```go +type ScalarResponse[T any] struct { + RowsAffected uint32 + LastInsertId uint64 + Value T +} +``` + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + When inserting a row, this field contains the ID of the last inserted row. + This is useful for tables with auto-incrementing primary keys. + + + + The scalar value returned from the query. + diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx new file mode 100644 index 00000000..0e390c78 --- /dev/null +++ b/modus/sdk/go/neo4j.mdx @@ -0,0 +1,346 @@ +--- +title: "Neo4j APIs" +sidebarTitle: "Neo4j" +description: "Execute queries and mutations against a Neo4j database" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus Neo4j APIs allow you to run queries and mutations against a Neo4j +database. + +## Import + +To begin, import the `neo4j` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/neo4j" +``` + +## Neo4j APIs + +{/* */} + +The APIs in the `neo4j` package are below, organized by category. + + + +### Functions + +#### ExecuteQuery + +Executes a Cypher query on the Neo4j database. + +```go +func ExecuteQuery( + connection, + query string, + parameters map[string]any, + opts ...Neo4jOption +) (*EagerResult, error) +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + A Neo4j Cypher query to execute. + + + + A map of parameters to pass to the query. + + + + Optional arguments to pass to the query. Specify the database name using the + `WithDbName` option. + + +#### GetProperty + +Get a property from an entity at a given key and cast or decode it to a specific +type. + +```go +func GetProperty[T PropertyValue](e Entity, key string) (T, error) +``` + + + The type to cast or decode the value to. + + + + The entity to get the value from. + + + + The key of the value to get. + + +#### GetRecordValue + +Get a value from a record at a given key and cast or decode it to a specific +type. + +```go +func GetRecordValue[T RecordValue](record *Record, key string) (T, error) +``` + + + The type to cast or decode the value to. + + + + The record to get the value from. + + + + The key of the value to get. + + +### Types + +#### EagerResult + +The result of a Neo4j query or mutation. + +```go +type EagerResult struct { + Keys []string + Records []*Record +} +``` + + + The keys of the result. + + + + The records of the result. + + +#### Entity + +An interface representing possible entities in a Neo4j query result. + +```go +type Entity interface { + GetElementId() string + GetProperties() map[string]any +} +``` + + + Returns the ID of the entity. + + + + Returns the properties of the entity. + + +#### Node + +A node in a Neo4j query result. + +```go +type Node struct { + ElementId string + Labels []string + Props map[string]any +} +``` + + + The ID of the node. + + + + The labels of the node. + + + + The properties of the node. + + + + Returns the ID of the node. + + + + Returns the properties of the node. + + +#### Path + +A path in a Neo4j query result. + +```go +type Path struct { + Nodes []Node + Relationships []Relationship +} +``` + + + The nodes in the path. + + + + The relationships in the path. + + +#### Point2D + +A 2D point in a Neo4j query result. + +```go +type Point2D struct { + X float64 + Y float64 + SpatialRefId uint32 +} +``` + + + The X coordinate of the point. + + + + The Y coordinate of the point. + + + + The spatial reference ID of the point. + + +#### Point3D + +A 3D point in a Neo4j query result. + +```go +type Point3D struct { + X float64 + Y float64 + Z float64 + SpatialRefId uint32 +} +``` + + + The X coordinate of the point. + + + + The Y coordinate of the point. + + + + The Z coordinate of the point. + + + + The spatial reference ID of the point. + + +#### PropertyValue + +A type constraint for retrieving property values from a Neo4j entity. + +```go +type PropertyValue interface { + bool | int64 | float64 | string | + time.Time | []byte | []any | Point2D | Point3D +} +``` + +#### Record + +A record in a Neo4j query result. + +```go +type Record struct { + Keys []string + Values []string +} +``` + + + The values of the record. + + + + The keys of the record. + + + + Get the value of a record at a given key as a JSON encoded string. + + + Usually, you should use the `GetRecordValue[T](key)` function instead of this method. + + + + + Convert the record to a map of keys and JSON encoded string values. + + +#### RecordValue + +A type constraint for retrieving values from a Neo4j record. + +```go +type RecordValue interface { + bool | int64 | float64 | string | time.Time | + []byte | []any | map[string]any | + Node | Relationship | Path | Point2D | Point3D +} +``` + +#### Relationship + +A relationship in a Neo4j query result. + +```go +type Relationship struct { + ElementId string + StartElementId string + EndElementId string + Type string + Props map[string]any +} +``` + + + The ID of the relationship. + + + + The ID of the start node. + + + + The ID of the end node. + + + + The type of the relationship. + + + + The properties of the relationship. + + + + Returns the ID of the node. + + + + Returns the properties of the node. + diff --git a/modus/sdk/go/overview.mdx b/modus/sdk/go/overview.mdx new file mode 100644 index 00000000..f0a78e65 --- /dev/null +++ b/modus/sdk/go/overview.mdx @@ -0,0 +1,63 @@ +--- +title: "Modus Go SDK" +sidebarTitle: "Overview" +description: "Learn how to use the Modus Go SDK" +icon: "circle-info" +--- + +import SdkOverviewIntro from "/snippets/sdk-overview-intro.mdx" + + + +## Importing the APIs + +The Modus Go SDK organizes its APIs into packages based on their purpose. In +your Go code, you can import each package you'd like to use like this: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/" +``` + +## Available APIs + +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The following packages are available. They're grouped into categories below for +your convenience. Click on a package to view more information about its APIs. + +### Client APIs + +| Package | Purpose | +| :--------------------- | :--------------------------------------------------------------------------------- | +| [`http`](./http) | Provides access to external HTTP endpoints, including REST APIs and other services | +| [`graphql`](./graphql) | Allows you to securely call and fetch data from any GraphQL endpoint | + +### Database APIs + +| Package | Purpose | +| :--------------------------- | :---------------------------------------------- | +| [`dgraph`](./dgraph) | Access and modify data in a Dgraph database | +| [`mysql`](./mysql) | Access and modify data in a MySQL database | +| [`neo4j`](./neo4j) | Access and modify data in a Neo4j database | +| [`postgresql`](./postgresql) | Access and modify data in a PostgreSQL database | + +### Inference APIs + +| Package | Purpose | +| :------------------- | :--------------------------------------------------------------------------------------------- | +| [`models`](./models) | Invoke AI models, including large language models, embedding models, and classification models | + +### Storage APIs + +| Package | Purpose | +| :----------------------------- | :--------------------------------------------------------- | +| [`collections`](./collections) | Provides integrated storage and vector search capabilities | + +### System APIs + +| Package | Purpose | +| :------------------------- | :------------------------------------------------------- | +| [`console`](./console) | Provides logging, assertion, and timing functions | +| [`localtime`](./localtime) | Allows you to access the user's local time and time zone | diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx new file mode 100644 index 00000000..00f08f14 --- /dev/null +++ b/modus/sdk/go/postgresql.mdx @@ -0,0 +1,288 @@ +--- +title: "PostgreSQL APIs" +sidebarTitle: "PostgreSQL" +description: "Execute queries against a PostgreSQL database" +icon: "circle-small" +iconType: "solid" +--- + +import { SdkHeader } from "/snippets/sdk-header.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" + + + +The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any +PostgreSQL-compatible database platform. + +## Import + +To begin, import the `postgresql` package from the SDK: + +```go +import "github.com/hypermodeinc/modus/sdk/go/pkg/postgresql" +``` + +## PostgreSQL APIs + +{/* */} + +The APIs in the `postgresql` package are below, organized by category. + + + +### Functions + +#### Execute + +Execute a SQL statement against a PostgreSQL database, without any data +returned. Use this for insert, update, or delete operations, or for other SQL +statements that don't return data. + + + The `Execute` function is for operations that don't return data. However, some + insert/update/delete operations may still return data. In these cases, you can + use the `QueryScalar` or `Query` functions instead. + + +```go +func Execute(connection, statement string, params ...any) (*db.Response, error) +``` + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass parameters as arguments instead. + This can help to protect injection attacks and other security vulnerabilities. + + + + + + Optional parameters to include with the query. + + +#### Query + +Execute a SQL statement against a PostgreSQL database, returning a set of rows. +In the results, each row converts to an object of type `T`, with fields matching +the column names. + +```go +func Query[T any](connection, statement string, params ...any) (*db.QueryResponse[T], error) +``` + + + +Type of object to use for the data returned from the query. This can be any +type, including a custom type defined in your project. It should match the shape +of the row returned from the SQL query. + + + +Define custom types in the project's source code. All types must be JSON +serializable. You can also use built-in types such as strings, numbers, slices, +and maps. + +If working with PostgreSQL's `point` data type, you can use a [`Point`](#point) +or [`Location`](#location) object to represent the data. + + + + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass parameters as arguments instead. + This can help to protect injection attacks and other security vulnerabilities. + + + + + + Optional parameters to include with the query. + + +#### QueryScalar + +Execute a SQL statement against a PostgreSQL database, returning a single scalar +value. For example, the result could be a count, sum, or average, or it could be +an identifier. + +```go +func QueryScalar[T any](connection, statement string, params ...any) (*db.ScalarResponse[T], error) +``` + + + Type of object to use for the data returned from the query. This should + generally be a scalar data type, such as a number or string. It should match + the type of the data returned from the SQL query. + + + + Name of the connection, as [defined in the + manifest](/modus/app-manifest#connections). + + + + +SQL statement containing the query or mutation operation to execute. + + + While it's possible to directly include parameter values into your SQL + statement, it's highly recommended to pass parameters as arguments instead. + This can help to protect injection attacks and other security vulnerabilities. + + + + + + Optional parameters to include with the query. + + +### Types + +#### Location + +Represents a location on Earth, having `Longitude` and `Latitude` coordinates. + +Correctly serializes to and from PostgreSQL's point type, in (longitude, +latitude) order. + + + This struct is identical to the [Point](#point) struct, but uses different + field names. + + +```go +type Location struct { + Longitude float64 + Latitude float64 +} +``` + + + The longitude coordinate of the location, in degrees. + + + + The latitude coordinate of the location, in degrees. + + +#### Point + +Represents a point in 2D space, having `X` and `Y` coordinates. Correctly +serializes to and from PostgreSQL's point type, in (x, y) order. + + + This struct is identical to the [Location](#location) struct, but uses + different field names. + + +```go +type Point struct { + X float64 + Y float64 +} +``` + + + The X coordinate of the point. + + + + The Y coordinate of the point. + + +#### QueryResponse + +Represents the response from a [`Query`](#query) operation. + +```go +type QueryResponse[T any] struct { + RowsAffected uint32 + LastInsertId uint64 + Rows []T +} +``` + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + This field is available for other database types, but isn't populated for + PostgreSQL. Instead, use `Query` or `QueryScalar` with a `RETURNING` clause to + get the last inserted ID. + + + + An slice of objects, each representing a row returned from the query. Each + object has fields corresponding to the columns in the result set. + + +#### Response + +Represents the response from an [`Execute`](#execute) operation. + +```go +type Response struct { + RowsAffected uint32 + LastInsertId uint64 +} +``` + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + This field is available for other database types, but isn't populated for + PostgreSQL. Instead, use `Query` or `QueryScalar` with a `RETURNING` clause to + get the last inserted ID. + + +#### ScalarResponse + +Represents the response from a [`QueryScalar`](#queryscalar) operation. + +```go +type ScalarResponse[T any] struct { + RowsAffected uint32 + LastInsertId uint64 + Value T +} +``` + + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. + + + + This field is available for other database types, but isn't populated for + PostgreSQL. Instead, use `Query` or `QueryScalar` with a `RETURNING` clause to + get the last inserted ID. + + + + The scalar value returned from the query. + diff --git a/modus/sdk/neo4j.mdx b/modus/sdk/neo4j.mdx deleted file mode 100644 index 330a1b02..00000000 --- a/modus/sdk/neo4j.mdx +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Neo4j -description: "Execute queries and mutations against a Neo4j database" ---- - -The Modus Neo4j API allows you to run queries and mutations against a Neo4j -database. - -## Import - -To begin, import the `neo4j` namespace from the SDK: - - - -```ts AssemblyScript -import { neo4j } from "@hypermode/modus-sdk-as" -``` - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j -``` - - - -## Neo4j APIs - -{/* */} - -The APIs in the `neo4j` namespace are below, organized by category. - - - We're constantly introducing new APIs through ongoing development with early - users. [Open an issue](https://github.com/hypermodeinc/modus/issues) if you - have ideas on what would make Modus even more powerful for your next app! - - -### Functions - -#### executeQuery - -Execute a Neo4j query or mutation using a Neo4j query and parameters. - -```go -func ExecuteQuery(connectionName, query string, parameters map[string]any, opts ...Neo4jOption) (*EagerResult, error) -``` - - - Name of the connection, as [defined in the - manifest](../app-manifest#connections). - - - - A Neo4j query to execute. - - - - A map of parameters to pass to the query. - - - - Optional arguments to pass to the query. Specify the database name using the - `WithDbName` option. - - -#### GetRecordValue - -Get the value of a record at a given key, and cast as a type. - -```go -func GetRecordValue[T RecordValue](record *Record, key string) (T, error) -``` - - - The record to get the value from. - - - - The key of the value to get. - - - - The type to cast the value as. - - -#### Get - -Get the value of a record object at a given key as a string. - -```go -func (r *Record) Get(key string) (string, error) -``` - - - The key of the value to get. - - -#### AsMap - -Convert a record object to a map. - -```go -func (r *Record) AsMap() map[string]string -``` - -#### GetProperty - -Get the value of an `Entity` (`Node`, `Path`, or `Relationship`) property, and -cast as a type. - -```go -func GetProperty[T PropertyValue](e Entity, key string) (T, error) -``` - - - The entity to get the property from. - - - - The key of the property to get. - - - - The type to cast the property as. - - -### Types - -#### EagerResult - -The result of a Neo4j query or mutation. - -```go -type EagerResult struct { - Keys []string - Records []*Record -} -``` - - - The keys of the result. - - - - The records of the result. - - -#### Record - -A record in a Neo4j query result. - -```go -type Record struct { - Values []string - Keys []string -} -``` - - - The values of the record. - - - - The keys of the record. - - -#### RecordValue - -A value of a record in a Neo4j query result. - -```go -type RecordValue interface { - bool | int64 | float64 | string | - time.Time | - []byte | []any | map[string]any | - Node | Relationship | Path | Point2D | Point3D -} -``` - -#### Entity - -An interface representing possible entities in a Neo4j query result. `Node`, -`Relationship`, and `Path` implement this interface. - -```go -type Entity interface { - GetElementId() string - GetProperties() map[string]any -} -``` - -#### Node - -A node in a Neo4j query result. - -```go -type Node struct { - ElementId string `json:"ElementId"` - Labels []string `json:"Labels"` - Props map[string]any `json:"Props"` -} -``` - - - The ID of the node. - - - - The labels of the node. - - - - The properties of the node. - - -#### Relationship - -A relationship in a Neo4j query result. - -```go -type Relationship struct { - ElementId string `json:"ElementId"` - StartElementId string `json:"StartElementId"` - EndElementId string `json:"EndElementId"` - Type string `json:"Type"` - Props map[string]any `json:"Props"` -} -``` - - - The ID of the relationship. - - - - The ID of the start node. - - - - The ID of the end node. - - - - The type of the relationship. - - - - The properties of the relationship. - - -#### Path - -A path in a Neo4j query result. - -```go -type Path struct { - Nodes []Node `json:"Nodes"` - Relationships []Relationship `json:"Relationships"` -} -``` - - - The nodes in the path. - - - - The relationships in the path. - - -#### PropertyValue - -A value of a property in a Neo4j query result. - -```go -type PropertyValue interface { - bool | int64 | float64 | string | - time.Time | []byte | []any | Point2D | Point3D -} -``` - -#### Point2D - -A 2D point in a Neo4j query result. - -```go -type Point2D struct { - X float64 - Y float64 - SpatialRefId uint32 -} -``` - - - The X coordinate of the point. - - - - The Y coordinate of the point. - - - - The spatial reference ID of the point. - - -#### Point3D - -A 3D point in a Neo4j query result. - -```go -type Point3D struct { - X float64 - Y float64 - Z float64 - SpatialRefId uint32 -} -``` - - - The X coordinate of the point. - - - - The Y coordinate of the point. - - - - The Z coordinate of the point. - - - - The spatial reference ID of the point. - diff --git a/snippets/sdk-header.mdx b/snippets/sdk-header.mdx new file mode 100644 index 00000000..5edef758 --- /dev/null +++ b/snippets/sdk-header.mdx @@ -0,0 +1,23 @@ +export const SdkHeader = ({language, feature}) => ( + +

While each Modus SDK offers similar functionality, the APIs and usage may vary between languages.

+

Modus {feature} APIs are documented on the following pages:

+
    + {(() =>{ + const languages = ["AssemblyScript", "Go"]; + const page = feature.toLowerCase().replace(/\W/g, ""); + return languages.map((lang) => { + if (lang === language) { + return ( +
  • {lang} {feature} APIs (this page)
    • + ) + } else { + return ( +
  • {lang} {feature} APIs
    • + ) + } + }) + })()} +
+ +) diff --git a/snippets/sdk-overview-intro.mdx b/snippets/sdk-overview-intro.mdx new file mode 100644 index 00000000..faec49c7 --- /dev/null +++ b/snippets/sdk-overview-intro.mdx @@ -0,0 +1,20 @@ +The Modus {language} SDK provides a set of APIs that allow you to interact +with various databases and services in Modus apps written in {language}. +It's designed to work seamlessly with the Modus platform, enabling you to build +powerful applications with ease. + + + +The Modus SDKs come in multiple languages, each following the conventions for +that language, including its capabilities and limitations. While each SDK +provides similar features, the APIs may differ slightly between languages. Be +sure to refer to the documentation for the specific SDK you're using. + +Wherever possible, we've tried to keep the APIs consistent across languages. +However, you may find differences in the APIs due to language-specific +constraints. + +If you have any questions or need help, please reach out to us via the `#modus` +channel on the [Hypermode Discord server](https://discord.hypermode.com/). + + diff --git a/snippets/sdk-tip.mdx b/snippets/sdk-tip.mdx new file mode 100644 index 00000000..efaf7ac8 --- /dev/null +++ b/snippets/sdk-tip.mdx @@ -0,0 +1,5 @@ + + We're constantly introducing new APIs through ongoing development with early users. + Please [open an issue](https://github.com/hypermodeinc/modus/issues) + if you have ideas on what would make Modus even more powerful for your next app! + diff --git a/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index e9b03e6c..c8cfc586 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -1,64 +1,78 @@ -agentic -alterSchema +[Aa]gentic +[Aa]lterSchema +[Bb]oolean +[Cc]ollections +[Cc]omputeDistance +[Cc]omputeSimilarity +[Cc]onsole +[Dd]eserialize +[Dd]istilbert +[Dd]ropAll +[Dd]ropAttr +[Ee]mbedder +[Ee]xecuteQuery +[Ff]etch +[Gg]etLabels +[Gg]etModel +[Gg]etNamespaces +[Gg]etText +[Gg]etTexts +[Gg]etVector +[Hh]ardcoding +[Hh]yp +[Hh]ypercategories +[Hh]ypermode +[Ii]nferencing +[Ll]og +[Mm]odus +[Nn]amespace +[Nn]amespaces +[Nn]nClassify +[Oo]nboarding +[Pp]arams +[Qq]ueryScalar +[Ss]erializable +[Ss]erverless +[Tt]imeEnd +[Tt]imeLog +[Tt]riaging +[Uu]nexported +[Uu]psert +[Uu]psertBatch Anthropic APIs +AssemblyScript AWS -boolean CLI|cli -[Cc]onsole -[Cc]ollections -computeSimilarity CRUD -[Dd]graph -distilbert -dropAll -dropAttr -embedder -executeQuery -[Ff]etch -getLabels -getModel -getText -getTexts -getVector +Debugf +Dgraph|dgraph +DQL +Errorf GitHub|github GraphiQL GraphQL|graphql gRPC -hardcoding HTTP|http Hugging Face -[Hh]yp -[Hh]ypercategories -[Hh]ypermode -inferencing -[Ll]og +IANA +Infof +ISO LLM -[Mm]odus -namespace -namespaces -nnClassify -npm +Logf +MySQL|mysql +NPM|npm NQuads -onboarding -[Pp]arams PostgreSQL|postgresql PUT -queryScalar repo -REST +REST|[Rr]est Scattergories SDK|sdk -serializable -[Ss]erverless -timeEnd -triaging -upsert +TLS URL|url +UTC urql UUID -[Dd]eserialize -upsertBatch -computeDistance -getNamespaces -timeLog \ No newline at end of file +Warnf +WASM