From 61082fc89ce96d223b7ff2f0c9cda9357817aefe Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Mon, 27 Jan 2025 16:41:13 -0800 Subject: [PATCH 01/22] Split SDK docs by language --- mint.json | 72 +- .../sdk/{ => assemblyscript}/collections.mdx | 0 modus/sdk/{ => assemblyscript}/console.mdx | 0 modus/sdk/{ => assemblyscript}/dgraph.mdx | 0 modus/sdk/{ => assemblyscript}/graphql.mdx | 0 modus/sdk/{ => assemblyscript}/http.mdx | 0 modus/sdk/{ => assemblyscript}/models.mdx | 0 modus/sdk/{ => assemblyscript}/neo4j.mdx | 0 modus/sdk/{ => assemblyscript}/postgresql.mdx | 0 modus/sdk/go/collections.mdx | 724 ++++++++++++++++++ modus/sdk/go/console.mdx | 154 ++++ modus/sdk/go/dgraph.mdx | 219 ++++++ modus/sdk/go/graphql.mdx | 208 +++++ modus/sdk/go/http.mdx | 321 ++++++++ modus/sdk/go/models.mdx | 177 +++++ modus/sdk/go/neo4j.mdx | 330 ++++++++ modus/sdk/go/postgresql.mdx | 347 +++++++++ 17 files changed, 2544 insertions(+), 8 deletions(-) rename modus/sdk/{ => assemblyscript}/collections.mdx (100%) rename modus/sdk/{ => assemblyscript}/console.mdx (100%) rename modus/sdk/{ => assemblyscript}/dgraph.mdx (100%) rename modus/sdk/{ => assemblyscript}/graphql.mdx (100%) rename modus/sdk/{ => assemblyscript}/http.mdx (100%) rename modus/sdk/{ => assemblyscript}/models.mdx (100%) rename modus/sdk/{ => assemblyscript}/neo4j.mdx (100%) rename modus/sdk/{ => assemblyscript}/postgresql.mdx (100%) create mode 100644 modus/sdk/go/collections.mdx create mode 100644 modus/sdk/go/console.mdx create mode 100644 modus/sdk/go/dgraph.mdx create mode 100644 modus/sdk/go/graphql.mdx create mode 100644 modus/sdk/go/http.mdx create mode 100644 modus/sdk/go/models.mdx create mode 100644 modus/sdk/go/neo4j.mdx create mode 100644 modus/sdk/go/postgresql.mdx diff --git a/mint.json b/mint.json index 5583dc61..4bbf5c84 100644 --- a/mint.json +++ b/mint.json @@ -43,6 +43,12 @@ "url": "modus" } ], + "redirects": [ + { + "source": "/modus/sdk/:slug*", + "destination": "/modus/sdk/assemblyscript/:slug*" + } + ], "navigation": [ { "group": "Getting Started", @@ -98,14 +104,64 @@ { "group": "API 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", + "pages": [ + { + "group": "Client APIs", + "pages": [ + "modus/sdk/assemblyscript/graphql", + "modus/sdk/assemblyscript/http", + "modus/sdk/assemblyscript/models" + ] + }, + { + "group": "Database APIs", + "pages": [ + "modus/sdk/assemblyscript/dgraph", + "modus/sdk/assemblyscript/neo4j", + "modus/sdk/assemblyscript/postgresql" + ] + }, + { + "group": "System APIs", + "pages": ["modus/sdk/assemblyscript/console"] + }, + { + "group": "Storage APIs", + "pages": ["modus/sdk/assemblyscript/collections"] + } + ] + }, + { + "group": "Go", + "pages": [ + { + "group": "Client APIs", + "pages": [ + "modus/sdk/go/graphql", + "modus/sdk/go/http", + "modus/sdk/go/models" + ] + }, + { + "group": "Database APIs", + "pages": [ + "modus/sdk/go/dgraph", + "modus/sdk/go/neo4j", + "modus/sdk/go/postgresql" + ] + }, + { + "group": "System APIs", + "pages": ["modus/sdk/go/console"] + }, + { + "group": "Storage APIs", + "pages": ["modus/sdk/go/collections"] + } + ] + } ] }, { diff --git a/modus/sdk/collections.mdx b/modus/sdk/assemblyscript/collections.mdx similarity index 100% rename from modus/sdk/collections.mdx rename to modus/sdk/assemblyscript/collections.mdx diff --git a/modus/sdk/console.mdx b/modus/sdk/assemblyscript/console.mdx similarity index 100% rename from modus/sdk/console.mdx rename to modus/sdk/assemblyscript/console.mdx diff --git a/modus/sdk/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx similarity index 100% rename from modus/sdk/dgraph.mdx rename to modus/sdk/assemblyscript/dgraph.mdx diff --git a/modus/sdk/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx similarity index 100% rename from modus/sdk/graphql.mdx rename to modus/sdk/assemblyscript/graphql.mdx diff --git a/modus/sdk/http.mdx b/modus/sdk/assemblyscript/http.mdx similarity index 100% rename from modus/sdk/http.mdx rename to modus/sdk/assemblyscript/http.mdx diff --git a/modus/sdk/models.mdx b/modus/sdk/assemblyscript/models.mdx similarity index 100% rename from modus/sdk/models.mdx rename to modus/sdk/assemblyscript/models.mdx diff --git a/modus/sdk/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx similarity index 100% rename from modus/sdk/neo4j.mdx rename to modus/sdk/assemblyscript/neo4j.mdx diff --git a/modus/sdk/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx similarity index 100% rename from modus/sdk/postgresql.mdx rename to modus/sdk/assemblyscript/postgresql.mdx diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx new file mode 100644 index 00000000..169aecb9 --- /dev/null +++ b/modus/sdk/go/collections.mdx @@ -0,0 +1,724 @@ +--- +title: Collections +description: "Add storage and vector search capabilities to your functions." +--- + +The Modus Collection API allows you to add vector search within your functions. + +## Import + +To begin, import the `collections` namespace from the SDK: + + + +```go Go +import github.com/hypermodeinc/modus/sdk/go/pkg/collections +``` + +```ts AssemblyScript +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 + +#### 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 +collections.upsert( + collection: string, + key: string | null, + text: string, + labels: string[] = [], + namespace: string = "", +): CollectionMutationResult +``` + + + Name of the collection, as [defined in the + manifest](../app-manifest#collections). + + + + The unique identifier for the item in the namespace. If null, the function + generates a unique identifier. + + + + The text of the item to add to the collection. + + + + An optional array of labels to associate with the item. + + + + Associates the item with a specific namespace. Defaults to an empty namespace + if not provided. + + +#### 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 +collections.upsertBatch( + collection: string, + keys: string[] | null, + texts: string[], + labelsArr: string[][] = [], + namespace: string = "", +): CollectionMutationResult +``` + + + Name of the collection, as [defined in the + manifest](../app-manifest#collections). + + + + Array of keys for the item to add to the collection. If you pass `null` for + any key, Hypermode assigns a new UUID as the key for the item. + + + + Array of texts for the items to add to the collection. + + + + An optional array of arrays of labels to associate with the items. + + + + Associates the item with a specific namespace. Defaults to an empty namespace + if not provided. + + +#### remove + +Removes an item from the collection. + +```go +collections.remove( + collection: string, + key: string, + namespace: string = "", +): CollectionMutationResult +``` + + + Name of the collection, as [defined in the + manifest](../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. + + +### 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. + + + Modus uses the same embedder for both inserting text into the collection, and + for the text used when searching the collection. + + +```go +collections.search( + collection: string, + searchMethod: string, + text: string, + limit: i32, + returnText: bool = false, + namespaces: string[] = [], +): CollectionSearchResult +``` + + + Name of the collection, as [defined in the + manifest](../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. + + + + A flag to return the texts in the response. + + + + 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.searchByVector( + collection: string, + searchMethod: string, + vector: f64[], + limit: i32, + returnText: bool = false, + namespaces: string[] = [], +): CollectionSearchResult +``` + + + Name of the collection, as [defined in the + manifest](../app-manifest#collections). + + + + The search method used to calculate embedding for vector & search against. + + + + 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. + + +#### nnClassify + +Classify an item in the collection using previous vectors' labels. + +```go + collections.nnClassify( + collection: string, + searchMethod: string, + text: string, + namespace: string = "", +): CollectionClassificationResult +``` + + + Name of the collection, as [defined in the + manifest](../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. + + +#### computeDistance + +Computes distance between two keys in a collection using a search method's +embedder. + +```go +collections.computeDistance( + collection: string, + searchMethod: string, + key1: string, + key2: string, + namespace: string = "", +): CollectionSearchResultObject +``` + + + 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. + + + + The namespace to search the items from. Defaults to the default namespace if + not provided. + + +#### getText + +Gets an item's text from a collection, give the item's key. + +```go +collections.getText( + collection: string, + key: string, + namespace: string = "", +): string +``` + + + Name of the collection, as [defined in the + manifest](../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. + + +#### getTexts + +Get all items from a collection. The result is a map of key to text for all +items in the collection. + +```go +collections.getTexts( + collection: string, + namespace: string = "", +): Map +``` + + + Name of the collection, as [defined in the + manifest](../app-manifest#collections). + + + + The namespace to get the items from. Defaults to the default namespace if not + provided. + + +#### getNamespaces + +Get all namespaces in a collection. + +```go +collections.getNamespaces( + collection: string, +): string[] +``` + + + Name of the collection, as [defined in the + manifest](../app-manifest#collections). + + +#### getVector + +Get the vector for an item in a collection. + +```go +collections.getVector( + collection: string, + searchMethod: string, + key: string, + namespace: string = "", +): f64[] +``` + + + Name of the collection, as [defined in the + manifest](../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. + + +#### getLabels + +Get the labels for an item in a collection. + +```go +collections.getLabels( + collection: string, + key: string, + namespace: string = "", +): string[] +``` + + + Name of the collection, as [defined in the + manifest](../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. + + +### 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 +collections.recomputeSearchMethod( + collection: string, + searchMethod: string, + namespace: string = "", +): collections.SearchMethodMutationResult +``` + + + Name of the collection, as [defined in the + manifest](../app-manifest#collections). + + + + The search method to recompute embeddings for. + + + + The namespace to use. Defaults to the default namespace if not provided. + + +### Objects + +#### CollectionMutationResult + +```go +class CollectionMutationResult { + 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. + + + + The status of the operation. + + + + Error message, if any. + + + + A boolean indicating whether the operation completed successfully. Use this to + confirm success before handling the result. + + + + The operation performed. + + + + The keys of the items affected by the operation. + + +#### CollectionSearchResult + +```go +class CollectionSearchResult { + collection: string; + status: CollectionStatus; + error: string; + isSuccessful: bool; + searchMethod: string; + objects: CollectionSearchResultObject[]; +} +``` + +Represents the result of a search operation on a collection. + + + Name of the collection. + + + + The status of the operation. + + + + Error message, if any. + + + + A boolean indicating whether the operation completed successfully. Use this to + confirm success before handling the result. + + + + The search method used in the operation. + + + + The search results. + + +#### CollectionSearchResultObject + +```go +class CollectionSearchResultObject { + namespace: string; + key: string; + text: string; + labels: string[]; + distance: f64; + score: f64; +} +``` + +Represents an object in the search results. + + + 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. + + +#### CollectionClassificationResult + +```go +class CollectionClassificationResult { + collection: string; + status: CollectionStatus; + error: string; + isSuccessful: bool; + searchMethod: string; + labelsResult: CollectionClassificationLabelObject[]; + cluster: CollectionClassificationResultObject[]; +} +``` + +Represents the result of a classification operation on a collection. + + + Name of the collection. + + + + The status of the operation. + + + + Error message, if any. + + + + A boolean indicating whether the operation completed successfully. Use this to + confirm success before handling the result. + + + + The search method used in the operation. + + + + The classification labels. + + + + The classification results. + + +#### CollectionClassificationLabelObject + +```go +class CollectionClassificationLabelObject { + label: string; + confidence: f64; +} +``` + +Represents a classification label. + + + The classification label. + + + + The confidence score of the classification label. + + +#### 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 classification labels. + + + + The distance of the item from the classification labels. + + + + The similarity score of the item classified. + + +#### CollectionStatus + +```go +enum CollectionStatus { + Success = "success"; + Error = "error"; +} +``` + +The status of a collection operation. + + + The operation was successful. + + + + The operation encountered an error. + + +#### SearchMethodMutationResult + +```go +class SearchMethodMutationResult { + 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. + + + + The status of the operation. + + + + Error message, if any. + + + + A boolean indicating whether the operation completed successfully. Use this to + confirm success before handling the result. + + + + 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..edd3e3bd --- /dev/null +++ b/modus/sdk/go/console.mdx @@ -0,0 +1,154 @@ +--- +title: Console +description: "Capture errors and debugging information in your functions" +--- + +The Modus Console API allows 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. + + +The Console API mimics the behavior of the AssemblyScript +[`console`](https://www.assemblyscript.org/stdlib/console.html) object, but +directs the output to Hypermode as follows: + +- All console output is available in the runtime logs. When hosting on + Hypermode, the logs are available in the "Function Runs" section of the + Console UI. +- Output from `console.error` is also sent to the GraphQL response. +- Errors thrown with the `throw` keyword are also sent to the GraphQL response. + +## Console APIs + +{/* */} + +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 + +#### assert + +Asserts that a condition is true, and logs an error if it's not. + +```go +console.assert(assertion: any, message?: string): void +``` + + + The condition to assert. Typically a boolean value. In the case of an object, + asserts that the object isn't `null`. + + + + An error message to log, if the assertion is false. + + +### Logging Functions + +#### log + +Generate a log message, with no particular logging level. + +```go +console.log(message?: string): void +``` + + + A message you want to log. + + +#### debug + +Generate a log message with the "debug" logging level. + +```go +console.debug(message?: string): void +``` + + + A debug message you want to log. + + +#### info + +Generate a log message with the "info" logging level. + +```go +console.info(message?: string): void +``` + + + An informational message you want to log. + + +#### warn + +Generate a log message with the "warning" logging level. + +```go +console.warn(message?: string): void +``` + + + A warning message you want to log. + + +#### error + +Generate a log message with the "error" logging level. + +```go +console.error(message?: string): void +``` + + + An error message you want to log. + + +### Timing Functions + +#### time + +Starts a new timer using the specified label. + +```go +console.time(label?: string): void +``` + + + An optional label for the timer. + + +#### timeLog + +Logs the current value of a timer previously started with `console.time`. + +```go +console.timeLog(label?: string): void +``` + + + An optional label for the timer. + + +#### timeEnd + +Logs the current value of a timer previously started with `console.time`, and +discards the timer. + +```go +console.timeEnd(label?: string): void +``` + + + 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..253f9059 --- /dev/null +++ b/modus/sdk/go/dgraph.mdx @@ -0,0 +1,219 @@ +--- +title: Dgraph +description: "Execute queries and mutations against a Dgraph database" +--- + +The Modus Dgraph API allows 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 +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 + +Execute a Dgraph query or mutation using a Dgraph Request object. + +```go +function execute(connectionName: string, request: Request): Response; +``` + + + Name of the connection, as [defined in the + manifest](../app-manifest#connections). + + + + A Dgraph [`Request`](#request) object, describing the query or mutation to + execute. + + +#### alterSchema + +Alter the schema of a Dgraph database. + +```go +function alterSchema(connectionName: string, schema: string): string; +``` + + + Name of the connection, as [defined in the + manifest](../app-manifest#connections). + + + + The schema to apply to the Dgraph database. + + +#### dropAttr + +Drop an attribute from a Dgraph schema. + +```go +function dropAttr(connectionName: string, attr: string): string; +``` + + + Name of the connection, as [defined in the + manifest](../app-manifest#connections). + + + + The attribute to drop from the Dgraph schema. + + +#### dropAll + +Drop all data from a Dgraph database. + +```go +function dropAll(connectionName: string): string; +``` + + + Name of the connection, as [defined in the + manifest](../app-manifest#connections). + + +### Objects + +#### Request + +A Dgraph request object, used to execute queries and mutations. + +```go +class Request { + constructor(Query: Query | null = null, Mutations: Mutation[] | null = null); + query: Query = new Query(); + mutations: Mutation[] = []; +} +``` + + + Creates a new `Request` object with the given `query` and `mutations`. + +The [`query`](#query) and [`mutations`](#mutation) fields are optional and +default to `null`. + + + + + A Dgraph [`query`](#query) object. + + + + An array of Dgraph [`mutation`](#mutation) objects. + + +#### Query + +A Dgraph query object, used to execute queries. + +```go +class Query { + constructor(query: string = "", variables: Variables = new Variables()); + query: string = ""; + variables: Map = new Map(); +} +``` + + + Creates a new `Query` object with the given `query` and `variables`. `query` + is a Dgraph Query Language (DQL) query string, and `variables` is a + [`Variables`](#variables) object. + + + + The DQL query to execute. + + + + A map of query variables. + + +#### Variables + +A Variables object used to set query variables in a Dgraph query. + +```go +class Variables { + public set(name: string, value: T): void; + public toMap(): Map; +} +``` + + + 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. + +```go +class Mutation { + constructor( + public setJson: string = "", + public delJson: string = "", + public setNquads: string = "", + public delNquads: string = "", + public condition: string = "", + ) +} +``` + + + 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 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. + diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx new file mode 100644 index 00000000..94d2269e --- /dev/null +++ b/modus/sdk/go/graphql.mdx @@ -0,0 +1,208 @@ +--- +title: GraphQL +description: "Access external GraphQL data sources from your functions" +--- + +The Modus GraphQL API allows 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 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. + +```go +graphql.execute ( + connection: string, + statement: string, + 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`. + +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). + + + + 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`](#variables) object + instead. This can help to prevent against injection attacks and other security + vulnerabilities. + + + + + + Optional variables to include with the query. + +See the details of the [`Variables`](#variables) object for more information. + + + +### Objects + +#### 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. + + + 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 can be of any type that's JSON serializable, including strings, +numbers, boolean values, arrays, maps, and custom objects decorated with +`@json`. + + + + + + Serializes the variables to a JSON string for inclusion in the GraphQL + operation. The `execute` function calls this automatically when you pass a + `Variables` object. You typically don't need to call it directly. + + +#### 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. + + + 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`. + + + + + 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`. + + + +#### ErrorResult + +```go +class ErrorResult { + 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. + + + + 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 +class CodeLocation { + line: u32; + column: u32; +} +``` + +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..dc860b12 --- /dev/null +++ b/modus/sdk/go/http.mdx @@ -0,0 +1,321 @@ +--- +title: HTTP +description: "Access external HTTP endpoints from your functions" +--- + +The Modus HTTP API allows 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. + + + 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. + +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` namespace from the SDK: + + + +```go Go +import github.com/hypermodeinc/modus/sdk/go/pkg/http +``` + +```ts AssemblyScript +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 + +#### fetch + +Invoke an HTTP endpoint to retrieve data or trigger external action. + +Returns a [`Response`](#response) object with the HTTP response data. + +```go +http.fetch( + requestOrUrl: string | Request, + options: RequestOptions = new RequestOptions(), +): Response +``` + + + 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. + + + + + A [`RequestOptions`](#requestoptions) object with additional options for the + request, such as the HTTP method, headers, and body. + + +### Objects + +#### Content + +```go +class Content { + static from(value: any): Content; + readonly data: ArrayBuffer; + 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. + + + + The raw binary content data. + + + + 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 in the shape + of type `T`, and returns it as a value of type `T`. + + +#### Header + +```go +class Header { + name: string; + values: string[]; +} +``` + +Represents an HTTP request or response header. + + + The name of the header. + + + + An array of values for the header. Typically a header has a single value, but + some headers can have multiple values. + + +#### Headers + +```go +class Headers { + static from( + value: string[][] | Map | Map, + ): 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: + +- A `string[][]`, where each inner array contains a header name and value. +- A `Map`, where the keys are header names and the values are + header values. +- A `Map`, where the keys are header names and the values are + arrays of header values. + + + + + Appends a new header with the given `name` and `value` to the collection. + + + + Returns a `string[][]`, where each inner array contains a header name and + value. + + + + Returns the value of the header with the given `name`, or `null` 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 + +```go +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; +} +``` + +Represents an HTTP request to make. + + + 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"`. + +The optional `options` parameter is a [`RequestOptions`](#requestoptions) object +that's used to set the HTTP method, headers, and body if needed. + + + + + Creates a new `Request` object by cloning the given `request` and applying the + `options` to it. + + + + 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 [`Headers`](#headers) object. + + + + The raw binary content data of the request body. + + + + Interprets the request body as a UTF-8 encoded string, and returns it as a + `string` value. + + + + Interprets the request body as a UTF-8 encoded string containing JSON in the + shape of type `T`, and returns it as a value of type `T`. + + +#### RequestOptions + +```go +class RequestOptions { + 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. + + + + + 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 +class Response { + readonly status: u16; + readonly statusText: string; + readonly headers: Headers; + readonly body: ArrayBuffer; + readonly ok: bool; + text(): string; + json(): T; +} +``` + +Represents the response received from the HTTP server. + + + 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 [`Headers`](#headers) + object. + + + + 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. + + + + + Interprets the response body content as a UTF-8 encoded string, and returns it + as a `string` value. + + + + Interprets the response body content as a UTF-8 encoded string containing JSON + in the shape of type `T`, and returns it as a value of type `T`. + diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx new file mode 100644 index 00000000..404b4778 --- /dev/null +++ b/modus/sdk/go/models.mdx @@ -0,0 +1,177 @@ +--- +title: Models +description: "Invoke AI models from your functions" +--- + +The Modus Models API allows 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. + +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. + + +For your reference, several complete examples for using the Models API 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` 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 { ClassificationModel } from "@hypermode/modus-sdk-as/models/experimental/classification" + ``` + + + + +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` 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 + +#### getModel + +Get a model instance by name and type. + + ```go + models.getModel(modelName: string): T + ``` + + + The type of model to return. This can be any class that extends the `Model` + base class. + + + + The name of the model to retrieve. This must match the name of a model defined + in your project's manifest file. + + +### Objects + +#### Model + + ```go + abstract class Model { + debug: boolean; + info: ModelInfo; + invoke(input: TInput): TOutput; + } + ``` + +The base class for all models that Hypermode functions can invoke. + + + If you are implementing a custom model, you should extend this class. You'll + also need classes 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. + + + + 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`. + + + + Information about the model set by the Hypermode 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. + + + +This class 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 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. + + + + + 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/neo4j.mdx b/modus/sdk/go/neo4j.mdx new file mode 100644 index 00000000..330a1b02 --- /dev/null +++ b/modus/sdk/go/neo4j.mdx @@ -0,0 +1,330 @@ +--- +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/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx new file mode 100644 index 00000000..ec5f0c53 --- /dev/null +++ b/modus/sdk/go/postgresql.mdx @@ -0,0 +1,347 @@ +--- +title: PostgreSQL +description: "Execute queries against a PostgreSQL database" +--- + +The Modus PostgreSQL API allows 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 +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 + +#### 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, 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). + + +```go +function postgresql.execute ( + connectionName: string, + statement: string, + params?: Params +): Response +``` + + + Name of the connection, as [defined in the + manifest](../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. + + + + + 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 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, + 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 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). + + + + 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. + + + + + 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 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, + 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](../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. + + + + + Optional parameters to include with the query. + +See the details of the [`Params`](#params) object for more information. + + + +### Objects + +#### Params + +```go +class Params { + public push(value: any): void; + public toJSON(): string; +} +``` + +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. + + + 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 + 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. + + +#### Response + +```go +class Response { + error: string | null; + rowsAffected: u32; +} +``` + +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 number of rows affected by the operation. + + +#### QueryResponse + +```go +class QueryResponse { + error: string | null; + rowsAffected: u32; + 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. + + + + An array of objects, each representing a row returned from the query. Each + object has fields corresponding to the columns in the result set. + + +#### ScalarResponse + +```go +class ScalarResponse { + error: string | null; + rowsAffected: u32; + value: T; +} +``` + +Represents the response from a [`queryScalar`](#queryscalar) 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 scalar value returned from the query. + + +#### Point + +```go +class Point { + x: f64, + y: f64, +} +``` + +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. + + + + The y coordinate of the point. + + +#### 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. + + + + The latitude coordinate of the location, in degrees. + From e5a1657327b10ae85c2bb8334261c1976a6a1a82 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Tue, 28 Jan 2025 09:47:32 -0800 Subject: [PATCH 02/22] Add SDK snippets --- .trunk/trunk.yaml | 1 + modus/sdk/assemblyscript/collections.mdx | 10 +++--- modus/sdk/assemblyscript/console.mdx | 10 +++--- modus/sdk/assemblyscript/dgraph.mdx | 10 +++--- modus/sdk/assemblyscript/graphql.mdx | 10 +++--- modus/sdk/assemblyscript/http.mdx | 10 +++--- modus/sdk/assemblyscript/models.mdx | 10 +++--- modus/sdk/assemblyscript/neo4j.mdx | 10 +++--- modus/sdk/assemblyscript/postgresql.mdx | 9 +++-- modus/sdk/go/collections.mdx | 10 +++--- modus/sdk/go/console.mdx | 10 +++--- modus/sdk/go/dgraph.mdx | 10 +++--- modus/sdk/go/graphql.mdx | 10 +++--- modus/sdk/go/http.mdx | 10 +++--- modus/sdk/go/models.mdx | 10 +++--- modus/sdk/go/neo4j.mdx | 10 +++--- modus/sdk/go/postgresql.mdx | 10 +++--- snippets/sdk-snippets.mdx | 34 +++++++++++++++++++ styles/config/vocabularies/general/accept.txt | 3 +- 19 files changed, 116 insertions(+), 81 deletions(-) create mode 100644 snippets/sdk-snippets.mdx 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/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index 169aecb9..e862d395 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -3,6 +3,10 @@ title: Collections description: "Add storage and vector search capabilities to your functions." --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Collection API allows you to add vector search within your functions. ## Import @@ -27,11 +31,7 @@ import { collections } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index edd3e3bd..3c0f6ead 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -3,6 +3,10 @@ title: Console description: "Capture errors and debugging information in your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Console API allows you to capture information from your functions, such as errors and other information that can help you debug your functions. @@ -27,11 +31,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 diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 253f9059..73f330fd 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -3,6 +3,10 @@ title: Dgraph description: "Execute queries and mutations against a Dgraph database" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Dgraph API allows you to run queries and mutations against a Dgraph database. @@ -28,11 +32,7 @@ import { dgraph } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index 94d2269e..2b8dc5db 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -3,6 +3,10 @@ title: GraphQL description: "Access external GraphQL data sources from your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus GraphQL API allows you to securely call and fetch data from any GraphQL endpoint. @@ -28,11 +32,7 @@ import { http } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index dc860b12..aa2ae03d 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -3,6 +3,10 @@ title: HTTP description: "Access external HTTP endpoints from your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus HTTP API allows 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 @@ -43,11 +47,7 @@ import { http } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/assemblyscript/models.mdx b/modus/sdk/assemblyscript/models.mdx index 404b4778..b92d9889 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -3,6 +3,10 @@ title: Models description: "Invoke AI models from your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Models API allows you to invoke AI models directly from your functions, irrespective of the model's host. @@ -67,11 +71,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 diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index 330a1b02..08c902c6 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -3,6 +3,10 @@ title: Neo4j description: "Execute queries and mutations against a Neo4j database" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Neo4j API allows you to run queries and mutations against a Neo4j database. @@ -28,11 +32,7 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j 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 diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index ec5f0c53..60f70ab6 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -3,6 +3,9 @@ title: PostgreSQL description: "Execute queries against a PostgreSQL database" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + The Modus PostgreSQL API allows you to run queries against PostgreSQL or any PostgreSQL-compatible database platform. @@ -28,11 +31,7 @@ import { postgresql } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index 169aecb9..5facf1d8 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -3,6 +3,10 @@ title: Collections description: "Add storage and vector search capabilities to your functions." --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Collection API allows you to add vector search within your functions. ## Import @@ -27,11 +31,7 @@ import { collections } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index edd3e3bd..86a39039 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -3,6 +3,10 @@ title: Console description: "Capture errors and debugging information in your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Console API allows you to capture information from your functions, such as errors and other information that can help you debug your functions. @@ -27,11 +31,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 diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 253f9059..e1c84061 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -3,6 +3,10 @@ title: Dgraph description: "Execute queries and mutations against a Dgraph database" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Dgraph API allows you to run queries and mutations against a Dgraph database. @@ -28,11 +32,7 @@ import { dgraph } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index 94d2269e..8c7a1578 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -3,6 +3,10 @@ title: GraphQL description: "Access external GraphQL data sources from your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus GraphQL API allows you to securely call and fetch data from any GraphQL endpoint. @@ -28,11 +32,7 @@ import { http } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index dc860b12..58098b00 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -3,6 +3,10 @@ title: HTTP description: "Access external HTTP endpoints from your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus HTTP API allows 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 @@ -43,11 +47,7 @@ import { http } from "@hypermode/modus-sdk-as" 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 diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx index 404b4778..15910f8d 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -3,6 +3,10 @@ title: Models description: "Invoke AI models from your functions" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Models API allows you to invoke AI models directly from your functions, irrespective of the model's host. @@ -67,11 +71,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 diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index 330a1b02..319ef20d 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -3,6 +3,10 @@ title: Neo4j description: "Execute queries and mutations against a Neo4j database" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus Neo4j API allows you to run queries and mutations against a Neo4j database. @@ -28,11 +32,7 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j 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 diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index ec5f0c53..d00c1a58 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -3,6 +3,10 @@ title: PostgreSQL description: "Execute queries against a PostgreSQL database" --- +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + + + The Modus PostgreSQL API allows you to run queries against PostgreSQL or any PostgreSQL-compatible database platform. @@ -28,11 +32,7 @@ import { postgresql } from "@hypermode/modus-sdk-as" 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 diff --git a/snippets/sdk-snippets.mdx b/snippets/sdk-snippets.mdx new file mode 100644 index 00000000..8dbb8f98 --- /dev/null +++ b/snippets/sdk-snippets.mdx @@ -0,0 +1,34 @@ +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"]; + return languages.map((lang) => { + if (lang === language) { + return ( +
  • {lang} {feature} APIs (this page)
    • + ) + } else { + return ( +
  • {lang} {feature} APIs
    • + ) + } + }) + })()} +
+ +) + +export const SdkTip = () => ( + +

+ We're constantly introducing new APIs through ongoing development with early users. + {" "} + Open an issue + {" "} + 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..ad2b27c6 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -2,6 +2,7 @@ agentic alterSchema Anthropic APIs +AssemblyScript AWS boolean CLI|cli @@ -61,4 +62,4 @@ UUID upsertBatch computeDistance getNamespaces -timeLog \ No newline at end of file +timeLog From d13e9ad76339b556c6d0edf4605040712fe4f1be Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Tue, 28 Jan 2025 10:23:49 -0800 Subject: [PATCH 03/22] Adjust wording --- modus/sdk/assemblyscript/collections.mdx | 2 +- modus/sdk/assemblyscript/console.mdx | 8 ++++---- modus/sdk/assemblyscript/dgraph.mdx | 2 +- modus/sdk/assemblyscript/graphql.mdx | 2 +- modus/sdk/assemblyscript/http.mdx | 2 +- modus/sdk/assemblyscript/models.mdx | 10 +++++----- modus/sdk/assemblyscript/neo4j.mdx | 2 +- modus/sdk/assemblyscript/postgresql.mdx | 2 +- modus/sdk/go/collections.mdx | 2 +- modus/sdk/go/console.mdx | 8 ++++---- modus/sdk/go/dgraph.mdx | 2 +- modus/sdk/go/graphql.mdx | 4 ++-- modus/sdk/go/http.mdx | 2 +- modus/sdk/go/models.mdx | 10 +++++----- modus/sdk/go/neo4j.mdx | 2 +- modus/sdk/go/postgresql.mdx | 2 +- 16 files changed, 31 insertions(+), 31 deletions(-) diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index e862d395..d7084171 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Collection API allows you to add vector search within your functions. +The Modus Collection APIs allow you to add vector search within your functions. ## Import diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index 3c0f6ead..f62f507c 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -7,15 +7,15 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Console API allows you to capture information from your functions, +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 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: diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 73f330fd..08cecafb 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Dgraph API allows you to run queries and mutations against a Dgraph +The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph database. ## Import diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index 2b8dc5db..cb9ab983 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus GraphQL API allows you to securely call and fetch data from any +The Modus GraphQL APIs allow you to securely call and fetch data from any GraphQL endpoint. ## Import diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index aa2ae03d..3256b887 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus HTTP API allows you to securely call and fetch data from an HTTP +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. diff --git a/modus/sdk/assemblyscript/models.mdx b/modus/sdk/assemblyscript/models.mdx index b92d9889..45a4619e 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -7,12 +7,12 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Models API allows you to invoke AI models directly from your +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 @@ -20,7 +20,7 @@ create custom classes for any model you like, by extending from the base `Model` class. -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 diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index 08c902c6..d37b7058 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Neo4j API allows you to run queries and mutations against a Neo4j +The Modus Neo4j APIs allow you to run queries and mutations against a Neo4j database. ## Import diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index 60f70ab6..ffdad268 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -6,7 +6,7 @@ description: "Execute queries against a PostgreSQL database" import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus PostgreSQL API allows you to run queries against PostgreSQL or any +The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any PostgreSQL-compatible database platform. ## Import diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index 5facf1d8..a1f4a41f 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Collection API allows you to add vector search within your functions. +The Modus Collection APIs allow you to add vector search within your functions. ## Import diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index 86a39039..dedbc4c7 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -7,15 +7,15 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Console API allows you to capture information from your functions, +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 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: diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index e1c84061..00f1ce60 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Dgraph API allows you to run queries and mutations against a Dgraph +The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph database. ## Import diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index 8c7a1578..d8f9a5fc 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus GraphQL API allows you to securely call and fetch data from any +The Modus GraphQL APIs allow you to securely call and fetch data from any GraphQL endpoint. ## Import @@ -39,7 +39,7 @@ The APIs in the `graphql` namespace are below, organized by category. #### execute Execute a GraphQL statement to call a query or apply mutation against a GraphQL -API endpoint. +endpoint. ```go graphql.execute ( diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index 58098b00..6b726b19 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus HTTP API allows you to securely call and fetch data from an HTTP +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. diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx index 15910f8d..0fe685f7 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -7,12 +7,12 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Models API allows you to invoke AI models directly from your +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 @@ -20,7 +20,7 @@ create custom classes for any model you like, by extending from the base `Model` class. -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 diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index 319ef20d..a5c73b00 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus Neo4j API allows you to run queries and mutations against a Neo4j +The Modus Neo4j APIs allow you to run queries and mutations against a Neo4j database. ## Import diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index d00c1a58..962f1c4e 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -7,7 +7,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" -The Modus PostgreSQL API allows you to run queries against PostgreSQL or any +The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any PostgreSQL-compatible database platform. ## Import From 23075a8b6ba3a6d8b1c7bd51a458e3b84919f89a Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Tue, 28 Jan 2025 10:23:39 -0800 Subject: [PATCH 04/22] Fix syntax --- modus/sdk/assemblyscript/collections.mdx | 126 +++++++++++------------ modus/sdk/assemblyscript/console.mdx | 18 ++-- modus/sdk/assemblyscript/dgraph.mdx | 50 ++++----- modus/sdk/assemblyscript/graphql.mdx | 40 +++---- modus/sdk/assemblyscript/http.mdx | 80 +++++++------- modus/sdk/assemblyscript/models.mdx | 10 +- modus/sdk/assemblyscript/neo4j.mdx | 40 +++---- modus/sdk/assemblyscript/postgresql.mdx | 48 ++++----- modus/sdk/go/collections.mdx | 10 +- modus/sdk/go/dgraph.mdx | 10 +- modus/sdk/go/graphql.mdx | 10 +- modus/sdk/go/http.mdx | 10 +- modus/sdk/go/neo4j.mdx | 10 +- modus/sdk/go/postgresql.mdx | 10 +- 14 files changed, 188 insertions(+), 284 deletions(-) diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index d7084171..739b9c91 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -13,18 +13,10 @@ The Modus Collection APIs allow you to add vector search within your functions. To begin, import the `collections` namespace from the SDK: - - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/collections -``` - -```ts AssemblyScript +```ts import { collections } from "@hypermode/modus-sdk-as" ``` - - ## Collections APIs {/* */} @@ -44,7 +36,7 @@ Inserts or updates an item in a collection. not, it creates a new one. -```go +```ts collections.upsert( collection: string, key: string | null, @@ -86,7 +78,7 @@ Inserts or updates a batch of items into a collection. with the new text. -```go +```ts collections.upsertBatch( collection: string, keys: string[] | null, @@ -123,7 +115,7 @@ collections.upsertBatch( Removes an item from the collection. -```go +```ts collections.remove( collection: string, key: string, @@ -157,7 +149,7 @@ useful for finding items that match a search query based on semantic meaning. for the text used when searching the collection. -```go +```ts collections.search( collection: string, searchMethod: string, @@ -204,7 +196,7 @@ requiring precise similarity calculations between pre-computed embeddings. for the vector used when searching the collection. -```go +```ts collections.searchByVector( collection: string, searchMethod: string, @@ -244,7 +236,7 @@ collections.searchByVector( Classify an item in the collection using previous vectors' labels. -```go +```ts collections.nnClassify( collection: string, searchMethod: string, @@ -276,7 +268,7 @@ Classify an item in the collection using previous vectors' labels. Computes distance between two keys in a collection using a search method's embedder. -```go +```ts collections.computeDistance( collection: string, searchMethod: string, @@ -308,7 +300,7 @@ collections.computeDistance( Gets an item's text from a collection, give the item's key. -```go +```ts collections.getText( collection: string, key: string, @@ -335,7 +327,7 @@ collections.getText( Get all items from a collection. The result is a map of key to text for all items in the collection. -```go +```ts collections.getTexts( collection: string, namespace: string = "", @@ -356,7 +348,7 @@ collections.getTexts( Get all namespaces in a collection. -```go +```ts collections.getNamespaces( collection: string, ): string[] @@ -371,7 +363,7 @@ collections.getNamespaces( Get the vector for an item in a collection. -```go +```ts collections.getVector( collection: string, searchMethod: string, @@ -402,7 +394,7 @@ collections.getVector( Get the labels for an item in a collection. -```go +```ts collections.getLabels( collection: string, key: string, @@ -433,7 +425,7 @@ 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 +```ts collections.recomputeSearchMethod( collection: string, searchMethod: string, @@ -458,14 +450,14 @@ collections.recomputeSearchMethod( #### CollectionMutationResult -```go +```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[] } ``` @@ -498,14 +490,14 @@ Represents the result of a mutation operation on a collection. #### CollectionSearchResult -```go +```ts class CollectionSearchResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - searchMethod: string; - objects: CollectionSearchResultObject[]; + collection: string + status: CollectionStatus + error: string + isSuccessful: bool + searchMethod: string + objects: CollectionSearchResultObject[] } ``` @@ -538,14 +530,14 @@ Represents the result of a search operation on a collection. #### CollectionSearchResultObject -```go +```ts class CollectionSearchResultObject { - namespace: string; - key: string; - text: string; - labels: string[]; - distance: f64; - score: f64; + namespace: string + key: string + text: string + labels: string[] + distance: f64 + score: f64 } ``` @@ -573,15 +565,15 @@ Represents an object in the search results. #### CollectionClassificationResult -```go +```ts class CollectionClassificationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - searchMethod: string; - labelsResult: CollectionClassificationLabelObject[]; - cluster: CollectionClassificationResultObject[]; + collection: string + status: CollectionStatus + error: string + isSuccessful: bool + searchMethod: string + labelsResult: CollectionClassificationLabelObject[] + cluster: CollectionClassificationResultObject[] } ``` @@ -618,10 +610,10 @@ Represents the result of a classification operation on a collection. #### CollectionClassificationLabelObject -```go +```ts class CollectionClassificationLabelObject { - label: string; - confidence: f64; + label: string + confidence: f64 } ``` @@ -637,12 +629,12 @@ Represents a classification label. #### CollectionClassificationResultObject -```go +```ts class CollectionClassificationResultObject { - key: string; - labels: string[]; - distance: f64; - score: f64; + key: string + labels: string[] + distance: f64 + score: f64 } ``` @@ -666,7 +658,7 @@ Represents an object in the classification results. #### CollectionStatus -```go +```ts enum CollectionStatus { Success = "success"; Error = "error"; @@ -685,14 +677,14 @@ The status of a collection operation. #### SearchMethodMutationResult -```go +```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 } ``` diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index f62f507c..6b3d9a02 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -39,7 +39,7 @@ 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 +```ts console.assert(assertion: any, message?: string): void ``` @@ -58,7 +58,7 @@ console.assert(assertion: any, message?: string): void Generate a log message, with no particular logging level. -```go +```ts console.log(message?: string): void ``` @@ -70,7 +70,7 @@ console.log(message?: string): void Generate a log message with the "debug" logging level. -```go +```ts console.debug(message?: string): void ``` @@ -82,7 +82,7 @@ console.debug(message?: string): void Generate a log message with the "info" logging level. -```go +```ts console.info(message?: string): void ``` @@ -94,7 +94,7 @@ console.info(message?: string): void Generate a log message with the "warning" logging level. -```go +```ts console.warn(message?: string): void ``` @@ -106,7 +106,7 @@ console.warn(message?: string): void Generate a log message with the "error" logging level. -```go +```ts console.error(message?: string): void ``` @@ -120,7 +120,7 @@ console.error(message?: string): void Starts a new timer using the specified label. -```go +```ts console.time(label?: string): void ``` @@ -132,7 +132,7 @@ console.time(label?: string): void Logs the current value of a timer previously started with `console.time`. -```go +```ts console.timeLog(label?: string): void ``` @@ -145,7 +145,7 @@ console.timeLog(label?: string): void Logs the current value of a timer previously started with `console.time`, and discards the timer. -```go +```ts console.timeEnd(label?: string): void ``` diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 08cecafb..4762e9ce 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -14,18 +14,10 @@ database. 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 {/* */} @@ -40,8 +32,8 @@ The APIs in the `dgraph` namespace are below, organized by category. Execute a Dgraph query or mutation using a Dgraph Request object. -```go -function execute(connectionName: string, request: Request): Response; +```ts +function execute(connectionName: string, request: Request): Response ``` @@ -58,8 +50,8 @@ function execute(connectionName: string, request: Request): Response; Alter the schema of a Dgraph database. -```go -function alterSchema(connectionName: string, schema: string): string; +```ts +function alterSchema(connectionName: string, schema: string): string ``` @@ -75,8 +67,8 @@ function alterSchema(connectionName: string, schema: string): string; Drop an attribute from a Dgraph schema. -```go -function dropAttr(connectionName: string, attr: string): string; +```ts +function dropAttr(connectionName: string, attr: string): string ``` @@ -92,8 +84,8 @@ function dropAttr(connectionName: string, attr: string): string; Drop all data from a Dgraph database. -```go -function dropAll(connectionName: string): string; +```ts +function dropAll(connectionName: string): string ``` @@ -107,11 +99,11 @@ function dropAll(connectionName: string): string; A Dgraph request object, used to execute queries and mutations. -```go +```ts class Request { - constructor(Query: Query | null = null, Mutations: Mutation[] | null = null); - query: Query = new Query(); - mutations: Mutation[] = []; + constructor(Query: Query | null = null, Mutations: Mutation[] | null = null) + query: Query = new Query() + mutations: Mutation[] = [] } ``` @@ -135,11 +127,11 @@ default to `null`. 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(); + constructor(query: string = "", variables: Variables = new Variables()) + query: string = "" + variables: Map = new Map() } ``` @@ -161,10 +153,10 @@ class Query { A Variables object used to set query variables in a Dgraph query. -```go +```ts class Variables { - public set(name: string, value: T): void; - public toMap(): Map; + public set(name: string, value: T): void + public toMap(): Map } ``` @@ -181,7 +173,7 @@ class Variables { A Dgraph mutation object, used to execute mutations. -```go +```ts class Mutation { constructor( public setJson: string = "", diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index cb9ab983..73e8d2bc 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -14,18 +14,10 @@ GraphQL endpoint. To begin, import the `graphql` namespace from the SDK: - - -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/graphql -``` - -```ts AssemblyScript +```ts import { http } from "@hypermode/modus-sdk-as" ``` - - ## GraphQL APIs {/* */} @@ -39,9 +31,9 @@ The APIs in the `graphql` namespace are below, organized by category. #### execute Execute a GraphQL statement to call a query or apply mutation against a GraphQL -API endpoint. +endpoint. -```go +```ts graphql.execute ( connection: string, statement: string, @@ -93,10 +85,10 @@ See the details of the [`Variables`](#variables) object for more information. #### Variables -```go +```ts class Variables { - public set(name: string, value: any): void; - public toJSON(): string; + public set(name: string, value: any): void + public toJSON(): string } ``` @@ -133,10 +125,10 @@ numbers, boolean values, arrays, maps, and custom objects decorated with #### Response -```go +```ts class Response { - errors: ErrorResult[] | null; - data: T | null; + errors: ErrorResult[] | null + data: T | null } ``` @@ -162,11 +154,11 @@ is absent due to errors, this field is `null`. #### ErrorResult -```go +```ts class ErrorResult { - message: string; - locations: CodeLocation[] | null; - path: string[] | null; + message: string + locations: CodeLocation[] | null + path: string[] | null } ``` @@ -190,10 +182,10 @@ Each item in the array represents a segment of the path. #### CodeLocation -```go +```ts class CodeLocation { - line: u32; - column: u32; + line: u32 + column: u32 } ``` diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index 3256b887..f9c9eea7 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -29,18 +29,10 @@ repository, and aren't visible or accessible from your functions code. 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 {/* */} @@ -57,7 +49,7 @@ Invoke an HTTP endpoint to retrieve data or trigger external action. Returns a [`Response`](#response) object with the HTTP response data. -```go +```ts http.fetch( requestOrUrl: string | Request, options: RequestOptions = new RequestOptions(), @@ -85,12 +77,12 @@ than those defined in the manifest entry of the connection. #### Content -```go +```ts class Content { - static from(value: any): Content; - readonly data: ArrayBuffer; - text(): string; - json(): T; + static from(value: any): Content + readonly data: ArrayBuffer + text(): string + json(): T } ``` @@ -116,10 +108,10 @@ Represents content used in the body of an HTTP request or response. #### Header -```go +```ts class Header { - name: string; - values: string[]; + name: string + values: string[] } ``` @@ -136,14 +128,14 @@ Represents an HTTP request or response header. #### Headers -```go +```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 } ``` @@ -179,16 +171,16 @@ The `value` object must be one of the following types: #### Request -```go +```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 + text(): string + json(): T } ``` @@ -240,11 +232,11 @@ that's used to set the HTTP method, headers, and body if needed. #### RequestOptions -```go +```ts class RequestOptions { - method: string | null; - headers: Headers; - body: Content | null; + method: string | null + headers: Headers + body: Content | null } ``` @@ -273,15 +265,15 @@ Options for the HTTP request. #### Response -```go +```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 + text(): string + json(): T } ``` diff --git a/modus/sdk/assemblyscript/models.mdx b/modus/sdk/assemblyscript/models.mdx index 45a4619e..8b631bfa 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -35,13 +35,13 @@ To begin, import the `models` namespace from the SDK: - ```go + ```ts 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 + ```ts import github.com/hypermodeinc/modus/sdk/go/pkg/models/experimental ``` @@ -79,7 +79,7 @@ The APIs in the `models` namespace are below, organized by category. Get a model instance by name and type. - ```go + ```ts models.getModel(modelName: string): T ``` @@ -97,7 +97,7 @@ Get a model instance by name and type. #### Model - ```go + ```ts abstract class Model { debug: boolean; info: ModelInfo; @@ -144,7 +144,7 @@ The base class for all models that Hypermode functions can invoke. #### ModelInfo - ```go + ```ts class ModelInfo { readonly name: string; readonly fullName: string; diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index d37b7058..913f2ada 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -14,18 +14,10 @@ database. To begin, import the `neo4j` namespace from the SDK: - - -```ts AssemblyScript +```ts import { neo4j } from "@hypermode/modus-sdk-as" ``` -```go Go -import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j -``` - - - ## Neo4j APIs {/* */} @@ -40,7 +32,7 @@ The APIs in the `neo4j` namespace are below, organized by category. Execute a Neo4j query or mutation using a Neo4j query and parameters. -```go +```ts func ExecuteQuery(connectionName, query string, parameters map[string]any, opts ...Neo4jOption) (*EagerResult, error) ``` @@ -66,7 +58,7 @@ func ExecuteQuery(connectionName, query string, parameters map[string]any, opts Get the value of a record at a given key, and cast as a type. -```go +```ts func GetRecordValue[T RecordValue](record *Record, key string) (T, error) ``` @@ -86,7 +78,7 @@ func GetRecordValue[T RecordValue](record *Record, key string) (T, error) Get the value of a record object at a given key as a string. -```go +```ts func (r *Record) Get(key string) (string, error) ``` @@ -98,7 +90,7 @@ func (r *Record) Get(key string) (string, error) Convert a record object to a map. -```go +```ts func (r *Record) AsMap() map[string]string ``` @@ -107,7 +99,7 @@ func (r *Record) AsMap() map[string]string Get the value of an `Entity` (`Node`, `Path`, or `Relationship`) property, and cast as a type. -```go +```ts func GetProperty[T PropertyValue](e Entity, key string) (T, error) ``` @@ -129,7 +121,7 @@ func GetProperty[T PropertyValue](e Entity, key string) (T, error) The result of a Neo4j query or mutation. -```go +```ts type EagerResult struct { Keys []string Records []*Record @@ -148,7 +140,7 @@ type EagerResult struct { A record in a Neo4j query result. -```go +```ts type Record struct { Values []string Keys []string @@ -167,7 +159,7 @@ type Record struct { A value of a record in a Neo4j query result. -```go +```ts type RecordValue interface { bool | int64 | float64 | string | time.Time | @@ -181,7 +173,7 @@ type RecordValue interface { An interface representing possible entities in a Neo4j query result. `Node`, `Relationship`, and `Path` implement this interface. -```go +```ts type Entity interface { GetElementId() string GetProperties() map[string]any @@ -192,7 +184,7 @@ type Entity interface { A node in a Neo4j query result. -```go +```ts type Node struct { ElementId string `json:"ElementId"` Labels []string `json:"Labels"` @@ -216,7 +208,7 @@ type Node struct { A relationship in a Neo4j query result. -```go +```ts type Relationship struct { ElementId string `json:"ElementId"` StartElementId string `json:"StartElementId"` @@ -250,7 +242,7 @@ type Relationship struct { A path in a Neo4j query result. -```go +```ts type Path struct { Nodes []Node `json:"Nodes"` Relationships []Relationship `json:"Relationships"` @@ -269,7 +261,7 @@ type Path struct { A value of a property in a Neo4j query result. -```go +```ts type PropertyValue interface { bool | int64 | float64 | string | time.Time | []byte | []any | Point2D | Point3D @@ -280,7 +272,7 @@ type PropertyValue interface { A 2D point in a Neo4j query result. -```go +```ts type Point2D struct { X float64 Y float64 @@ -304,7 +296,7 @@ type Point2D struct { A 3D point in a Neo4j query result. -```go +```ts type Point3D struct { X float64 Y float64 diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index ffdad268..f9fa3e73 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -13,18 +13,10 @@ PostgreSQL-compatible database platform. 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 {/* */} @@ -49,7 +41,7 @@ statements that don't return data. multiple rows). -```go +```ts function postgresql.execute ( connectionName: string, statement: string, @@ -85,7 +77,7 @@ 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 +```ts function postgresql.query( connectionName: string, statement: string, @@ -138,7 +130,7 @@ 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 +```ts function postgresql.queryScalar ( connectionName: string, statement: string, @@ -178,10 +170,10 @@ See the details of the [`Params`](#params) object for more information. #### Params -```go +```ts class Params { - public push(value: any): void; - public toJSON(): string; + public push(value: any): void + public toJSON(): string } ``` @@ -223,10 +215,10 @@ numbers, boolean values, arrays, maps, and custom objects decorated with #### Response -```go +```ts class Response { - error: string | null; - rowsAffected: u32; + error: string | null + rowsAffected: u32 } ``` @@ -244,11 +236,11 @@ the base class for `QueryResponse` and `ScalarResponse`. #### QueryResponse -```go +```ts class QueryResponse { - error: string | null; - rowsAffected: u32; - rows: T[]; + error: string | null + rowsAffected: u32 + rows: T[] } ``` @@ -270,11 +262,11 @@ Represents the response from a [`query`](#query) operation. #### ScalarResponse -```go +```ts class ScalarResponse { - error: string | null; - rowsAffected: u32; - value: T; + error: string | null + rowsAffected: u32 + value: T } ``` @@ -295,7 +287,7 @@ Represents the response from a [`queryScalar`](#queryscalar) operation. #### Point -```go +```ts class Point { x: f64, y: f64, @@ -320,7 +312,7 @@ serializes to and from PostgreSQL's point type, in (x, y) order. #### Location -```go +```ts class Location { longitude: f64, latitude: f64, diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index a1f4a41f..b0e189bc 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -13,18 +13,10 @@ The Modus Collection APIs allow you to add vector search within your functions. To begin, import the `collections` namespace from the SDK: - - -```go Go +```go import github.com/hypermodeinc/modus/sdk/go/pkg/collections ``` -```ts AssemblyScript -import { collections } from "@hypermode/modus-sdk-as" -``` - - - ## Collections APIs {/* */} diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 00f1ce60..5e31d07c 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -14,18 +14,10 @@ database. To begin, import the `dgraph` namespace from the SDK: - - -```go Go +```go import github.com/hypermodeinc/modus/sdk/go/pkg/dgraph ``` -```ts AssemblyScript -import { dgraph } from "@hypermode/modus-sdk-as" -``` - - - ## Dgraph APIs {/* */} diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index d8f9a5fc..cca0dae8 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -14,18 +14,10 @@ GraphQL endpoint. To begin, import the `graphql` namespace from the SDK: - - -```go Go +```go import github.com/hypermodeinc/modus/sdk/go/pkg/graphql ``` -```ts AssemblyScript -import { http } from "@hypermode/modus-sdk-as" -``` - - - ## GraphQL APIs {/* */} diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index 6b726b19..05475ceb 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -29,18 +29,10 @@ repository, and aren't visible or accessible from your functions code. To begin, import the `http` namespace from the SDK: - - -```go Go +```go import github.com/hypermodeinc/modus/sdk/go/pkg/http ``` -```ts AssemblyScript -import { http } from "@hypermode/modus-sdk-as" -``` - - - ## HTTP APIs {/* */} diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index a5c73b00..e072da10 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -14,18 +14,10 @@ database. To begin, import the `neo4j` namespace from the SDK: - - -```ts AssemblyScript -import { neo4j } from "@hypermode/modus-sdk-as" -``` - -```go Go +```go import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j ``` - - ## Neo4j APIs {/* */} diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index 962f1c4e..8bcabbe7 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -14,18 +14,10 @@ PostgreSQL-compatible database platform. To begin, import the `postgresql` namespace from the SDK: - - -```go Go +```go import github.com/hypermodeinc/modus/sdk/go/pkg/postgresql ``` -```ts AssemblyScript -import { postgresql } from "@hypermode/modus-sdk-as" -``` - - - ## PostgreSQL APIs {/* */} From 2fead12b37edd8242d3003278e69efac696f2917 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Tue, 28 Jan 2025 12:39:24 -0800 Subject: [PATCH 05/22] fix paths --- modus/sdk/assemblyscript/collections.mdx | 26 ++++++++++++------------ modus/sdk/assemblyscript/dgraph.mdx | 8 ++++---- modus/sdk/assemblyscript/graphql.mdx | 2 +- modus/sdk/assemblyscript/http.mdx | 2 +- modus/sdk/assemblyscript/neo4j.mdx | 2 +- modus/sdk/assemblyscript/postgresql.mdx | 6 +++--- modus/sdk/go/collections.mdx | 18 ++++++++-------- modus/sdk/go/dgraph.mdx | 8 ++++---- modus/sdk/go/graphql.mdx | 2 +- modus/sdk/go/http.mdx | 2 +- modus/sdk/go/neo4j.mdx | 2 +- modus/sdk/go/postgresql.mdx | 4 ++-- 12 files changed, 41 insertions(+), 41 deletions(-) diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index 739b9c91..26e57496 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -48,7 +48,7 @@ collections.upsert( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -90,7 +90,7 @@ collections.upsertBatch( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -125,7 +125,7 @@ collections.remove( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -162,7 +162,7 @@ collections.search( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -209,7 +209,7 @@ collections.searchByVector( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -247,7 +247,7 @@ Classify an item in the collection using previous vectors' labels. Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -280,7 +280,7 @@ collections.computeDistance( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -310,7 +310,7 @@ collections.getText( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -336,7 +336,7 @@ collections.getTexts( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -356,7 +356,7 @@ collections.getNamespaces( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). #### getVector @@ -374,7 +374,7 @@ collections.getVector( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -404,7 +404,7 @@ collections.getLabels( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -435,7 +435,7 @@ collections.recomputeSearchMethod( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 4762e9ce..64ce8e0c 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -38,7 +38,7 @@ function execute(connectionName: string, request: Request): Response Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -56,7 +56,7 @@ function alterSchema(connectionName: string, schema: string): string Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -73,7 +73,7 @@ function dropAttr(connectionName: string, attr: string): string Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -90,7 +90,7 @@ function dropAll(connectionName: string): string Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). ### Objects diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index 73e8d2bc..d5b88d03 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -59,7 +59,7 @@ and maps. Name of the connection, as [defined in the - manifest](../app-manifest#connection). + manifest](../../app-manifest#connection). diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index f9c9eea7..2da831b1 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -14,7 +14,7 @@ JavaScript, but with some modifications to work with Hypermode Functions. 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](../../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 diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index 913f2ada..1367115c 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -38,7 +38,7 @@ func ExecuteQuery(connectionName, query string, parameters map[string]any, opts Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index f9fa3e73..ba9ca50b 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -51,7 +51,7 @@ function postgresql.execute ( Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -104,7 +104,7 @@ or [`Location`](#location) object to represent the data. Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -146,7 +146,7 @@ function postgresql.queryScalar ( Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index b0e189bc..a5996ea3 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -48,7 +48,7 @@ collections.upsert( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -90,7 +90,7 @@ collections.upsertBatch( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -125,7 +125,7 @@ collections.remove( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -162,7 +162,7 @@ collections.search( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -209,7 +209,7 @@ collections.searchByVector( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -247,7 +247,7 @@ Classify an item in the collection using previous vectors' labels. Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -310,7 +310,7 @@ collections.getText( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -374,7 +374,7 @@ collections.getVector( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). @@ -435,7 +435,7 @@ collections.recomputeSearchMethod( Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](../../app-manifest#collections). diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 5e31d07c..4ba0ef08 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -38,7 +38,7 @@ function execute(connectionName: string, request: Request): Response; Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -56,7 +56,7 @@ function alterSchema(connectionName: string, schema: string): string; Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -73,7 +73,7 @@ function dropAttr(connectionName: string, attr: string): string; Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -90,7 +90,7 @@ function dropAll(connectionName: string): string; Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). ### Objects diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index cca0dae8..762e80c4 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -59,7 +59,7 @@ and maps. Name of the connection, as [defined in the - manifest](../app-manifest#connection). + manifest](../../app-manifest#connection). diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index 05475ceb..ade31d3d 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -14,7 +14,7 @@ JavaScript, but with some modifications to work with Hypermode Functions. 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](../../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 diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index e072da10..8872de9d 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -38,7 +38,7 @@ func ExecuteQuery(connectionName, query string, parameters map[string]any, opts Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index 8bcabbe7..6964500f 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -52,7 +52,7 @@ function postgresql.execute ( Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). @@ -105,7 +105,7 @@ or [`Location`](#location) object to represent the data. Name of the connection, as [defined in the - manifest](../app-manifest#connections). + manifest](../../app-manifest#connections). From 2042559918b19be3c0e096a629795647f6190da5 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Tue, 28 Jan 2025 15:06:13 -0800 Subject: [PATCH 06/22] update nav --- mint.json | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/mint.json b/mint.json index 4bbf5c84..023bdb6b 100644 --- a/mint.json +++ b/mint.json @@ -111,8 +111,7 @@ "group": "Client APIs", "pages": [ "modus/sdk/assemblyscript/graphql", - "modus/sdk/assemblyscript/http", - "modus/sdk/assemblyscript/models" + "modus/sdk/assemblyscript/http" ] }, { @@ -124,12 +123,16 @@ ] }, { - "group": "System APIs", - "pages": ["modus/sdk/assemblyscript/console"] + "group": "Inference APIs", + "pages": ["modus/sdk/assemblyscript/models"] }, { "group": "Storage APIs", "pages": ["modus/sdk/assemblyscript/collections"] + }, + { + "group": "System APIs", + "pages": ["modus/sdk/assemblyscript/console"] } ] }, @@ -138,11 +141,7 @@ "pages": [ { "group": "Client APIs", - "pages": [ - "modus/sdk/go/graphql", - "modus/sdk/go/http", - "modus/sdk/go/models" - ] + "pages": ["modus/sdk/go/graphql", "modus/sdk/go/http"] }, { "group": "Database APIs", @@ -153,12 +152,16 @@ ] }, { - "group": "System APIs", - "pages": ["modus/sdk/go/console"] + "group": "Inference APIs", + "pages": ["modus/sdk/go/models"] }, { "group": "Storage APIs", "pages": ["modus/sdk/go/collections"] + }, + { + "group": "System APIs", + "pages": ["modus/sdk/go/console"] } ] } From ec5adc2ac576fdc2ac4ba593449e5e41831a2156 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Tue, 28 Jan 2025 17:55:51 -0800 Subject: [PATCH 07/22] Update SDK docs --- modus/sdk/assemblyscript/collections.mdx | 440 ++++++----- modus/sdk/assemblyscript/console.mdx | 24 +- modus/sdk/assemblyscript/dgraph.mdx | 161 ++-- modus/sdk/assemblyscript/graphql.mdx | 90 ++- modus/sdk/assemblyscript/http.mdx | 142 ++-- modus/sdk/assemblyscript/models.mdx | 106 ++- modus/sdk/assemblyscript/neo4j.mdx | 310 ++++---- modus/sdk/assemblyscript/postgresql.mdx | 280 ++++--- modus/sdk/go/collections.mdx | 696 +++++++++--------- modus/sdk/go/console.mdx | 180 ++++- modus/sdk/go/dgraph.mdx | 169 ++--- modus/sdk/go/graphql.mdx | 143 ++-- modus/sdk/go/http.mdx | 441 +++++++---- modus/sdk/go/models.mdx | 176 +++-- modus/sdk/go/neo4j.mdx | 300 ++++---- modus/sdk/go/postgresql.mdx | 317 ++++---- styles/config/vocabularies/general/accept.txt | 93 +-- 17 files changed, 2124 insertions(+), 1944 deletions(-) diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index 26e57496..f8ee3c03 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -37,7 +37,7 @@ Inserts or updates an item in a collection. ```ts -collections.upsert( +function upsert( collection: string, key: string | null, text: string, @@ -48,11 +48,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. @@ -79,7 +79,7 @@ Inserts or updates a batch of items into a collection. ```ts -collections.upsertBatch( +function upsertBatch( collection: string, keys: string[] | null, texts: string[], @@ -90,7 +90,7 @@ collections.upsertBatch( Name of the collection, as [defined in the - manifest](../../app-manifest#collections). + manifest](/modus/app-manifest#collections). @@ -116,7 +116,7 @@ collections.upsertBatch( Removes an item from the collection. ```ts -collections.remove( +function remove( collection: string, key: string, namespace: string = "", @@ -125,7 +125,7 @@ collections.remove( Name of the collection, as [defined in the - manifest](../../app-manifest#collections). + manifest](/modus/app-manifest#collections). @@ -139,178 +139,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. ```ts -collections.search( +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. ```ts -collections.searchByVector( +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. ```ts - collections.nnClassify( +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). - - - - The search method used to calculate embedding for text & search against. + manifest](/modus/app-manifest#collections). - - 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. ```ts -collections.computeDistance( +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. ```ts -collections.getText( +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. @@ -322,98 +290,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. ```ts -collections.getTexts( +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. - -```ts -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. + ```ts -collections.getVector( +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. + ```ts -collections.getLabels( +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 @@ -426,16 +424,16 @@ the method for embedding calculation and want to re-compute the embeddings for existing data in the collection. ```ts -collections.recomputeSearchMethod( +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). @@ -446,10 +444,12 @@ collections.recomputeSearchMethod( The namespace to use. Defaults to the default namespace if not provided. -### Objects +### Types #### CollectionMutationResult +Represents the result of a mutation operation on a collection. + ```ts class CollectionMutationResult { collection: string @@ -461,8 +461,6 @@ class CollectionMutationResult { } ``` -Represents the result of a mutation operation on a collection. - Name of the collection. @@ -488,21 +486,41 @@ Represents the result of a mutation operation on a collection. The keys of the items affected by the operation. -#### CollectionSearchResult +#### CollectionClassificationLabelObject + +Represents a classification label. ```ts -class CollectionSearchResult { +class CollectionClassificationLabelObject { + label: string + confidence: f64 +} +``` + + + 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 - objects: CollectionSearchResultObject[] + labelsResult: CollectionClassificationLabelObject[] + cluster: CollectionClassificationResultObject[] } ``` -Represents the result of a search operation on a collection. - Name of the collection. @@ -524,61 +542,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. + + +#### CollectionClassificationResultObject + +Represents an object in the classification results. ```ts -class CollectionSearchResultObject { - namespace: string +class CollectionClassificationResultObject { key: string - text: string labels: string[] distance: f64 score: f64 } ``` -Represents an object in the search results. - - - The namespace of the item found as part of the search. - - - 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 + +Represents the result of a search operation on a collection. ```ts -class CollectionClassificationResult { +class CollectionSearchResult { collection: string status: CollectionStatus error: string isSuccessful: bool searchMethod: string - labelsResult: CollectionClassificationLabelObject[] - cluster: CollectionClassificationResultObject[] + objects: CollectionSearchResultObject[] } ``` -Represents the result of a classification operation on a collection. - Name of the collection. @@ -600,73 +615,56 @@ Represents the result of a classification operation on a collection. The search method used in the operation. - - The classification labels. - - - - The classification results. - - -#### CollectionClassificationLabelObject - -```ts -class CollectionClassificationLabelObject { - label: string - confidence: f64 -} -``` - -Represents a classification label. - - - The classification label. + + The search results. - - The confidence score of the classification label. - +#### CollectionSearchResultObject -#### CollectionClassificationResultObject +Represents an object in the search results. ```ts -class CollectionClassificationResultObject { +class CollectionSearchResultObject { + namespace: string key: string + text: string labels: string[] distance: f64 score: f64 } ``` -Represents an object in the classification results. + + The namespace of the item found as part of the search. + - 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 +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. @@ -677,6 +675,8 @@ The status of a collection operation. #### SearchMethodMutationResult +Represents the result of a mutation operation on a search method. + ```ts class SearchMethodMutationResult { collection: string @@ -688,8 +688,6 @@ class SearchMethodMutationResult { } ``` -Represents the result of a mutation operation on a search method. - Name of the collection. diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index 6b3d9a02..ae4b0c85 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -11,8 +11,8 @@ 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 namespace 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 APIs mimic the behavior of the AssemblyScript @@ -40,10 +40,10 @@ 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. ```ts -console.assert(assertion: any, message?: string): void +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`. @@ -59,7 +59,7 @@ console.assert(assertion: any, message?: string): void Generate a log message, with no particular logging level. ```ts -console.log(message?: string): void +function log(message?: string): void ``` @@ -71,7 +71,7 @@ console.log(message?: string): void Generate a log message with the "debug" logging level. ```ts -console.debug(message?: string): void +function debug(message?: string): void ``` @@ -83,7 +83,7 @@ console.debug(message?: string): void Generate a log message with the "info" logging level. ```ts -console.info(message?: string): void +function info(message?: string): void ``` @@ -95,7 +95,7 @@ console.info(message?: string): void Generate a log message with the "warning" logging level. ```ts -console.warn(message?: string): void +function warn(message?: string): void ``` @@ -107,7 +107,7 @@ console.warn(message?: string): void Generate a log message with the "error" logging level. ```ts -console.error(message?: string): void +function error(message?: string): void ``` @@ -121,7 +121,7 @@ console.error(message?: string): void Starts a new timer using the specified label. ```ts -console.time(label?: string): void +function time(label?: string): void ``` @@ -133,7 +133,7 @@ console.time(label?: string): void Logs the current value of a timer previously started with `console.time`. ```ts -console.timeLog(label?: string): void +function timeLog(label?: string): void ``` @@ -146,7 +146,7 @@ Logs the current value of a timer previously started with `console.time`, and discards the timer. ```ts -console.timeEnd(label?: string): void +function timeEnd(label?: string): void ``` diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 64ce8e0c..90ad0b54 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -28,39 +28,34 @@ The APIs in the `dgraph` namespace are below, organized by category. ### Functions -#### execute +#### alterSchema -Execute a Dgraph query or mutation using a Dgraph Request object. +Alter the schema of a Dgraph database. ```ts -function execute(connectionName: string, request: Request): Response +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. ```ts -function alterSchema(connectionName: string, schema: string): string +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 @@ -68,59 +63,75 @@ function alterSchema(connectionName: string, schema: string): string Drop an attribute from a Dgraph schema. ```ts -function dropAttr(connectionName: string, attr: string): string +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. ```ts -function dropAll(connectionName: string): string +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. ```ts -class Request { - constructor(Query: Query | null = null, Mutations: Mutation[] | null = null) - query: Query = new Query() - mutations: Mutation[] = [] +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 @@ -129,7 +140,6 @@ A Dgraph query object, used to execute queries. ```ts class Query { - constructor(query: string = "", variables: Variables = new Variables()) query: string = "" variables: Map = new Map() } @@ -149,63 +159,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. ```ts -class Variables { - public set(name: string, value: T): void - public toMap(): Map +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 +Creates a new `Request` object with the given `query` and `mutations`. -A Dgraph mutation object, used to execute mutations. - -```ts -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/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index d5b88d03..c40aac23 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -34,36 +34,40 @@ Execute a GraphQL statement to call a query or apply mutation against a GraphQL endpoint. ```ts -graphql.execute ( +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 @@ -75,46 +79,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 -```ts -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`. + +{/* */} + + + @@ -125,6 +138,10 @@ numbers, boolean values, arrays, maps, and custom objects decorated with #### Response +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 @@ -132,12 +149,9 @@ class Response { } ``` -A response object from the GraphQL query. - -Either `errors` or `data` is present, depending on the result of the query. - - 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`. @@ -145,7 +159,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`. @@ -154,6 +169,8 @@ is absent due to errors, this field is `null`. #### ErrorResult +The details of an error incurred as part of a GraphQL operation. + ```ts class ErrorResult { message: string @@ -162,26 +179,27 @@ class ErrorResult { } ``` -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 +The location of specific code within a GraphQL statement. + ```ts class CodeLocation { line: u32 @@ -189,8 +207,6 @@ class CodeLocation { } ``` -The location of specific code within a GraphQL statement. - Line number within the GraphQL statement for the code. diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index 2da831b1..c6d2b1c7 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -12,10 +12,12 @@ 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. - - 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 @@ -23,7 +25,7 @@ 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 @@ -50,22 +52,27 @@ Invoke an HTTP endpoint to retrieve data or trigger external action. Returns a [`Response`](#response) object with the HTTP response data. ```ts -http.fetch( +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. + + @@ -73,27 +80,41 @@ than those defined in the manifest entry of the connection. request, such as the HTTP method, headers, and body. -### Objects +### Types #### Content +Represents content used in the body of an HTTP request or response. + ```ts class Content { - static from(value: any): Content + 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`. @@ -108,6 +129,8 @@ Represents content used in the body of an HTTP request or response. #### Header +Represents an HTTP request or response header. + ```ts class Header { name: string @@ -115,8 +138,6 @@ class Header { } ``` -Represents an HTTP request or response header. - The name of the header. @@ -128,6 +149,8 @@ Represents an HTTP request or response header. #### Headers +Represents a collection of HTTP headers. + ```ts class Headers { static from( @@ -139,12 +162,11 @@ class Headers { } ``` -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 @@ -171,6 +193,8 @@ The `value` object must be one of the following types: #### Request +Represents an HTTP request to make. + ```ts class Request { constructor(url: string, options?: RequestOptions) @@ -179,15 +203,15 @@ class Request { 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"`. @@ -217,7 +241,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`. @@ -232,6 +267,8 @@ that's used to set the HTTP method, headers, and body if needed. #### RequestOptions +Options for the HTTP request. + ```ts class RequestOptions { method: string | null @@ -240,31 +277,38 @@ class RequestOptions { } ``` -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 +Represents the response received from the HTTP server. + ```ts class Response { readonly status: u16 @@ -272,13 +316,12 @@ class Response { 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. @@ -294,12 +337,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/models.mdx b/modus/sdk/assemblyscript/models.mdx index 8b631bfa..4cf2d103 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -14,10 +14,10 @@ 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 APIs are available in @@ -33,33 +33,16 @@ use it for any task that an AI model can perform. To begin, import the `models` namespace from the SDK: - - - ```ts - import github.com/hypermodeinc/modus/sdk/go/pkg/models - ``` +```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: +You'll also need to import one or more classes for the model you are working +with. For example: - ```ts - 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 { ClassificationModel } from "@hypermode/modus-sdk-as/models/experimental/classification" - ``` - - - +```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 @@ -79,11 +62,11 @@ The APIs in the `models` namespace are below, organized by category. Get a model instance by name and type. - ```ts - 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 +76,11 @@ Get a model instance by name and type. in your project's manifest file. -### Objects +### Types #### Model - ```ts - 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 +89,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 - ```ts - 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 +136,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/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index 1367115c..ab296ca3 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -30,293 +30,239 @@ The APIs in the `neo4j` namespace are below, organized by category. #### executeQuery -Execute a Neo4j query or mutation using a Neo4j query and parameters. +Executes a Cypher query on the Neo4j database. ```ts -func ExecuteQuery(connectionName, query string, parameters map[string]any, opts ...Neo4jOption) (*EagerResult, error) +function executeQuery( + connection: string, + query: string, + parameters: Variables = new Variables(), + dbName: string = "neo4j", +): EagerResult ``` - + Name of the connection, as [defined in the - manifest](../../app-manifest#connections). + manifest](/modus/app-manifest#connections). - A Neo4j query to execute. + A Neo4j Cypher query to execute. - - A map of parameters to pass to the query. + + The 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. - -```ts -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. - -```ts -func (r *Record) Get(key string) (string, error) -``` - - - The key of the value to get. - - -#### AsMap - -Convert a record object to a map. - -```ts -func (r *Record) AsMap() map[string]string -``` - -#### GetProperty - -Get the value of an `Entity` (`Node`, `Path`, or `Relationship`) property, and -cast as a type. - -```ts -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. + + An optional database name to use. Defaults to "neo4j" if not provided. ### Types #### EagerResult -The result of a Neo4j query or mutation. +The result of a Neo4j query. ```ts -type EagerResult struct { - Keys []string - Records []*Record +class EagerResult { + Keys: string[] + Records: Record[] } ``` - + The keys of the result. - + The records of the result. -#### Record +#### Entity -A record in a Neo4j query result. +An abstract class representing possible entities in a Neo4j query result. ```ts -type Record struct { - Values []string - Keys []string +abstract class Entity { + elementId: string + props: DynamicMap } ``` - - The values of the record. + + The ID of the entity. - - The keys of the record. + + The properties of the entity. -#### RecordValue - -A value of a record in a Neo4j query result. - -```ts -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. - -```ts -type Entity interface { - GetElementId() string - GetProperties() map[string]any -} -``` - #### Node A node in a Neo4j query result. ```ts -type Node struct { - ElementId string `json:"ElementId"` - Labels []string `json:"Labels"` - Props map[string]any `json:"Props"` +class Node extends Entity { + elementId: string // from base class + props: DynamicMap // from base class + labels: string[] } ``` - + The ID of the node. - - The labels of the node. + + The properties of the node. - - The properties of the node. + + The labels of the node. -#### Relationship +#### Path -A relationship in a Neo4j query result. +A path in a Neo4j query result. ```ts -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"` +class Path { + nodes: Node[] + relationships: Relationship[] } ``` - - The ID of the relationship. + + The nodes in the path. - - The ID of the start node. + + The relationships in the path. - - The ID of the end node. +#### 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 type of the relationship. + + The Y coordinate of the point. - - The properties of the relationship. + + The spatial reference ID of the point. -#### Path +#### Point3D -A path in a Neo4j query result. +A 3D point in a Neo4j query result. ```ts -type Path struct { - Nodes []Node `json:"Nodes"` - Relationships []Relationship `json:"Relationships"` +class Point3D { + x: f64 + y: f64 + z: f64 + spatialRefId: u32 } ``` - - The nodes in the path. + + The X coordinate of the point. - - The relationships in the path. + + The Y coordinate of the point. + + + + The Z coordinate of the point. + + + + The spatial reference ID of the point. -#### PropertyValue +#### Record -A value of a property in a Neo4j query result. +A record in a Neo4j query result. ```ts -type PropertyValue interface { - bool | int64 | float64 | string | - time.Time | []byte | []any | Point2D | Point3D +class Record { + keys: string[] + values: string[] + get(key: string): string + getValue(key: string): T + asMap(): Map } ``` -#### Point2D + + The keys of the record. + -A 2D point in a Neo4j query result. + + The values of the record. + -```ts -type Point2D struct { - X float64 - Y float64 - SpatialRefId uint32 -} -``` + + Get a value from a record at a given key as a JSON encoded string. - - The X coordinate of the point. + + Usually, you should use `getValue(key)` instead of this method. + - - The Y coordinate of the point. + + Get a value from a record at a given key and cast or decode it to a specific + type. - - The spatial reference ID of the point. + + Convert the record to a map of keys and JSON encoded string values. -#### Point3D +#### Relationship -A 3D point in a Neo4j query result. +A relationship in a Neo4j query result. ```ts -type Point3D struct { - X float64 - Y float64 - Z float64 - SpatialRefId uint32 +class Relationship extends Entity { + elementId: string // from base class + props: DynamicMap // from base class + startElementId: string + endElementId: string + type: string } ``` - - The X coordinate of the point. + + The ID of the relationship. - - The Y coordinate of the point. + + The properties of the relationship. - - The Z coordinate of the point. + + The ID of the start node. - - The spatial reference ID of the point. + + The ID of the end node. + + + + The type of the relationship. diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index ba9ca50b..a6ef8a65 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -6,6 +6,7 @@ description: "Execute queries against a PostgreSQL database" import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" + The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any PostgreSQL-compatible database platform. @@ -42,30 +43,34 @@ statements that don't return data. ```ts -function postgresql.execute ( - connectionName: string, +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. @@ -78,19 +83,23 @@ In the results, each row converts to an object of type `T`, with fields matching the column names. ```ts -function postgresql.query( - connectionName: string, +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`. +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, @@ -99,26 +108,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. @@ -131,72 +145,107 @@ value. For example, the result could be a count, sum, or average, or it could be an identifier. ```ts -function postgresql.queryScalar ( - connectionName: string, +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 + +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 Params { - public push(value: any): void - public toJSON(): string +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 @@ -205,6 +254,11 @@ numbers, boolean values, arrays, maps, and custom objects decorated with + +{/* */} + + + @@ -213,46 +267,58 @@ numbers, boolean values, arrays, maps, and custom objects decorated with typically don't need to call it directly. -#### Response +#### 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 class is identical to the [Location](#location) class, but uses different + field names. + ```ts -class Response { - error: string | null - rowsAffected: u32 +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 +Represents the response from a [`query`](#query) operation. + ```ts class QueryResponse { 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. @@ -260,18 +326,19 @@ Represents the response from a [`query`](#query) operation. object has fields corresponding to the columns in the result set. -#### ScalarResponse +#### Response + +Represents the response from an [`execute`](#execute) operation. Also serves as +the base class for `QueryResponse` and `ScalarResponse`. ```ts -class ScalarResponse { +class Response { error: string | null rowsAffected: u32 - value: T + 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`. @@ -281,58 +348,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 + +Represents the response from a [`queryScalar`](#queryscalar) operation. ```ts -class Point { - x: f64, - y: f64, +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 - -```ts -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 index a5996ea3..e2f84554 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -11,7 +11,7 @@ The Modus Collection APIs allow you to add vector search within your functions. ## Import -To begin, import the `collections` namespace from the SDK: +To begin, import the `collections` package from the SDK: ```go import github.com/hypermodeinc/modus/sdk/go/pkg/collections @@ -21,13 +21,13 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/collections {/* */} -The APIs in the `collections` namespace are below, organized by category. +The APIs in the `collections` package are below, organized by category. ### Mutation Functions -#### upsert +#### Upsert Inserts or updates an item in a collection. @@ -37,22 +37,22 @@ Inserts or updates an item in a collection. ```go -collections.upsert( - collection: string, - key: string | null, - text: string, - labels: string[] = [], - namespace: string = "", -): CollectionMutationResult +func Upsert( + collection string, + key *string, + text string, + labels []string, + opts ...NamespaceOption +) (*CollectionMutationResult, error) ``` 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 `nil`, the function generates a unique identifier. @@ -60,16 +60,19 @@ collections.upsert( The text of the item to add to the collection. - - An optional array of labels to associate with the item. + + 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 +#### UpsertBatch Inserts or updates a batch of items into a collection. @@ -79,346 +82,361 @@ Inserts or updates a batch of items into a collection. ```go -collections.upsertBatch( - collection: string, - keys: string[] | null, - texts: string[], - labelsArr: string[][] = [], - namespace: string = "", -): CollectionMutationResult +func UpsertBatch( + collection string, + keys []string, + texts []string, + labelsArr [][]string, + opts ...NamespaceOption +) (*CollectionMutationResult, error) ``` Name of the collection, as [defined in the - manifest](../../app-manifest#collections). + manifest](/modus/app-manifest#collections). - - Array of keys for the item to add to the collection. If you pass `null` for - any key, Hypermode assigns a new UUID as the key for the item. + + 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. - - Array of texts for the items to add to the collection. + + Slice of texts for the items to add to the collection. - - An optional array of arrays of labels to associate with the items. + + 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 +#### Remove Removes an item from the collection. ```go -collections.remove( - collection: string, - key: string, - namespace: string = "", -): CollectionMutationResult +func Remove( + collection string, + key string, + opts ...NamespaceOption +) (*CollectionMutationResult, error) ``` Name of the collection, as [defined in the - manifest](../../app-manifest#collections). + 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 -#### search +#### ComputeDistance -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. - +Computes distance between two keys in a collection using a search method's +embedder. ```go -collections.search( - collection: string, - searchMethod: string, - text: string, - limit: i32, - returnText: bool = false, - namespaces: string[] = [], -): CollectionSearchResult +func ComputeDistance( + collection string, + searchMethod string, + key1 string, + key2 string, + opts ...NamespaceOption +) (*CollectionSearchResultObject, error) ``` 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 search method used to calculate embedding for key's texts. - - The text to compute natural language search on. + + Keys to compute similarity on. - - The number of result objects to return. - + + The namespace to search the items from. Defaults to the default namespace if + not provided. - - A flag to return the texts in the response. - +Pass `collections.WithNamespace("namespace")` to specify a namespace. - - A list of namespaces to search the item from. Defaults to the default - namespace if not provided. -#### searchByVector +#### NnClassify -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. - +Classify an item in the collection using previous vectors' labels. ```go -collections.searchByVector( - collection: string, - searchMethod: string, - vector: f64[], - limit: i32, - returnText: bool = false, - namespaces: string[] = [], -): CollectionSearchResult +func NnClassify( + collection string, + searchMethod string, + text string, + opts ...NamespaceOption +) (*CollectionClassificationResult, error) ``` 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 search method used to calculate embedding for text & search against. - - The vector to compute search on. + + The text to compute natural language search on. - - The number of result objects to return. - + + The namespace to search the items from. Defaults to the default namespace if + not provided. - - A flag to return the texts in the response. - +Pass `collections.WithNamespace("namespace")` to specify a namespace. - - An optional array of namespaces to search within. -#### nnClassify +#### GetLabels -Classify an item in the collection using previous vectors' labels. +Get the labels for an item in a collection. ```go - collections.nnClassify( - collection: string, - searchMethod: string, - text: string, - namespace: string = "", -): CollectionClassificationResult +func GetLabels( + collection string, + key string, + opts ...NamespaceOption +) ([]string, error) ``` 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 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. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. - - The namespace to search the items from. Defaults to the default namespace if - not provided. -#### computeDistance +#### GetNamespaces -Computes distance between two keys in a collection using a search method's -embedder. +Get all namespaces in a collection. ```go -collections.computeDistance( - collection: string, - searchMethod: string, - key1: string, - key2: string, - namespace: string = "", -): CollectionSearchResultObject +func GetNamespaces(collection string) ([]string, error) ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). - - - - The search method used to calculate embedding for key's texts. + manifest](/modus/app-manifest#collections). - - Keys to compute similarity on. - - - - The namespace to search the items from. Defaults to the default namespace if - not provided. - - -#### getText +#### GetText Gets an item's text from a collection, give the item's key. ```go -collections.getText( - collection: string, - key: string, - namespace: string = "", -): string +func GetText( + collection string, + key string, + opts ...NamespaceOption +) (string, error) ``` 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 namespace to get the item from. Defaults to the default namespace if not provided. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + -#### getTexts +#### GetTexts Get all items from a collection. The result is a map of key to text for all items in the collection. ```go -collections.getTexts( - collection: string, - namespace: string = "", -): Map +func GetTexts( + collection string, + opts ...NamespaceOption +) (map[string]string, error) ``` 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. + +Pass `collections.WithNamespace("namespace")` to specify a namespace. + -#### getNamespaces +#### GetVector -Get all namespaces in a collection. +Get the vector for an item in a collection. ```go -collections.getNamespaces( - collection: string, -): string[] +func GetVector( + collection string, + searchMethod string, + key string, + opts ...NamespaceOption +) ([]float32, error) ``` Name of the collection, as [defined in the - manifest](../app-manifest#collections). + manifest](/modus/app-manifest#collections). -#### getVector + + The search method used to calculate embedding for key's texts. + -Get the vector for an item in a collection. + + 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 -collections.getVector( - collection: string, - searchMethod: string, - key: string, - namespace: string = "", -): f64[] +func Search( + collection string, + searchMethod string, + text string, + opts ...SearchOption +) (*CollectionSearchResult, error) ``` 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. + + 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. + -#### getLabels +#### SearchByVector -Get the labels for an item in a collection. +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( - collection: string, - key: string, - namespace: string = "", -): string[] +func SearchByVector( + collection string, + searchMethod string, + vector []float32, + opts ...SearchOption +) (*CollectionSearchResult, error) ``` 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. + + + + 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 +#### 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 @@ -426,291 +444,271 @@ the method for embedding calculation and want to re-compute the embeddings for existing data in the collection. ```go -collections.recomputeSearchMethod( - collection: string, - searchMethod: string, - namespace: string = "", -): collections.SearchMethodMutationResult +func RecomputeSearchMethod( + collection string, + searchMethod string, + opts ...NamespaceOption +) (*SearchMethodMutationResult, error) ``` Name of the collection, as [defined in the - manifest](../../app-manifest#collections). + 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. + -### Objects +### Types -#### CollectionMutationResult +#### CollectionClassificationLabelObject + +Represents a classification label. ```go -class CollectionMutationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - operation: string; - keys: string[]; +type CollectionClassificationLabelObject struct { + Label string + Confidence float64 } ``` -Represents the result of a mutation operation on a collection. - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. + + The classification label. - - The operation performed. + + The confidence score of the classification label. - - The keys of the items affected by the operation. - +#### CollectionClassificationResult -#### CollectionSearchResult +Represents the result of a classification operation on a collection. ```go -class CollectionSearchResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - searchMethod: string; - objects: CollectionSearchResultObject[]; +type CollectionClassificationResult struct { + Collection string + Status string + Error string + SearchMethod string + LabelsResult []*CollectionClassificationLabelObject + Cluster []*CollectionClassificationResultObject } ``` -Represents the result of a search operation on a collection. - - + Name of the collection. - + The status of the operation. - + Error message, if any. - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. + + The search method used in the operation. - - The search method used in the operation. + + The classification labels. - - The search results. + + The classification results. -#### CollectionSearchResultObject +#### CollectionClassificationResultObject + +Represents an object in the classification results. ```go -class CollectionSearchResultObject { - namespace: string; - key: string; - text: string; - labels: string[]; - distance: f64; - score: f64; +type CollectionClassificationResultObject struct { + Key string + Labels []string + Distance float64 + Score float64 } ``` -Represents an object in the search results. - - - The namespace of the item found as part of the search. + + 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. - +#### CollectionMutationResult -#### CollectionClassificationResult +Represents the result of a mutation operation on a collection. ```go -class CollectionClassificationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - searchMethod: string; - labelsResult: CollectionClassificationLabelObject[]; - cluster: CollectionClassificationResultObject[]; +type CollectionMutationResult struct { + Collection string + Status string + Error string + Operation string + Keys []string } ``` -Represents the result of a classification operation on a collection. - - + Name of the collection. - + The status of the operation. - + Error message, if any. - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. - - - - The search method used in the operation. + + The operation performed. - - The classification labels. + + The keys of the items affected by the operation. - - The classification results. - +#### CollectionSearchResult -#### CollectionClassificationLabelObject +Represents the result of a search operation on a collection. ```go -class CollectionClassificationLabelObject { - label: string; - confidence: f64; +type CollectionSearchResult struct { + Collection string + Status string + Error string + SearchMethod string + Objects []*CollectionSearchResultObject } ``` -Represents a classification label. + + Name of the collection. + - - The classification label. + + The status of the operation. - - The confidence score of the classification label. + + Error message, if any. -#### CollectionClassificationResultObject + + The search method used in the operation. + + + + The search results. + + +#### CollectionSearchResultObject + +Represents an object in the search results. ```go -class CollectionClassificationResultObject { - key: string; - labels: string[]; - distance: f64; - score: f64; +type CollectionSearchResultObject struct { + Namespace string + Key string + Text string + Labels []string + Distance float64 + Score float64 } ``` -Represents an object in the classification results. + + The namespace of the item found as part of the search. + - - 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 +The status of a collection operation. + ```go -enum CollectionStatus { - Success = "success"; - Error = "error"; -} +type CollectionStatus = string + +const ( + Success CollectionStatus = "success" + Error CollectionStatus = "error" +) ``` -The status of a collection operation. +The operation was successful. - - The operation was successful. - - - - The operation encountered an error. - +The operation encountered an error. #### SearchMethodMutationResult +Represents the result of a mutation operation on a search method. + ```go -class SearchMethodMutationResult { - collection: string; - status: CollectionStatus; - error: string; - isSuccessful: bool; - operation: string; - searchMethod: string; +type SearchMethodMutationResult struct { + Collection string + Status string + Error string + Operation string + SearchMethod string } ``` -Represents the result of a mutation operation on a search method. - - + Name of the collection. - + The status of the operation. - + Error message, if any. - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. - - - + The operation performed. - + The search method affected by the operation. diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index dedbc4c7..d173258a 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -11,142 +11,242 @@ 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 namespace is globally available by default in - all functions, you don't need to import it. + +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. + -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: +## Import + +To begin, import the `console` package from the SDK: -- All console output is available in the runtime logs. When hosting on - Hypermode, the logs are available in the "Function Runs" section of the - Console UI. -- Output from `console.error` is also sent to the GraphQL response. -- Errors thrown with the `throw` keyword are also sent to the GraphQL response. +```go +import github.com/hypermodeinc/modus/sdk/go/pkg/console +``` ## Console APIs {/* */} -The APIs in the `console` namespace are below, organized by category. +The APIs in the `console` package are below, organized by category. ### Assertion Functions -#### assert +#### Assert Asserts that a condition is true, and logs an error if it's not. ```go -console.assert(assertion: any, message?: string): void +func Assert(condition bool, message string) ``` - - The condition to assert. Typically a boolean value. In the case of an object, - asserts that the object isn't `null`. + + The boolean condition to assert. - + An error message to log, if the assertion is false. ### Logging Functions -#### log + + 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 -console.log(message?: string): void +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. -#### debug + + Arguments that correspond to the format specifiers in the message. + + +#### Debug Generate a log message with the "debug" logging level. ```go -console.debug(message?: string): void +func Debug(message string) ``` - + A debug message you want to log. -#### info +#### 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 -console.info(message?: string): void +func Info(message string) ``` - + An informational message you want to log. -#### warn +#### 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 -console.warn(message?: string): void +func Warn(message string) ``` - + A warning message you want to log. -#### error +#### 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 -console.error(message?: string): void +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 +#### Time Starts a new timer using the specified label. ```go -console.time(label?: string): void +func Time(label ...string) ``` An optional label for the timer. -#### timeLog +#### TimeLog -Logs the current value of a timer previously started with `console.time`. +Logs the current value of a timer previously started with `console.Time`. ```go -console.timeLog(label?: string): void +func TimeLog(label string) ``` An optional label for the timer. -#### timeEnd +#### TimeEnd -Logs the current value of a timer previously started with `console.time`, and +Logs the current value of a timer previously started with `console.Time`, and discards the timer. ```go -console.timeEnd(label?: string): void +func TimeEnd(label string) ``` diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 4ba0ef08..27dfc420 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -12,7 +12,7 @@ database. ## Import -To begin, import the `dgraph` namespace from the SDK: +To begin, import the `dgraph` package from the SDK: ```go import github.com/hypermodeinc/modus/sdk/go/pkg/dgraph @@ -22,105 +22,111 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/dgraph {/* */} -The APIs in the `dgraph` namespace are below, organized by category. +The APIs in the `dgraph` package are below, organized by category. ### 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; +func AlterSchema(connection, schema string) error ``` - + 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; +func DropAll(connection string) error ``` - + 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 +#### DropAttr Drop an attribute from a Dgraph schema. ```go -function dropAttr(connectionName: string, attr: string): string; +func DropAttr(connection, attr string) error ``` - + 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; +func Execute(connection string, request *Request) (*Response, error) ``` - + Name of the connection, as [defined in the - manifest](../../app-manifest#connections). + manifest](/modus/app-manifest#connections). -### Objects + + A pointer to a Dgraph [`Request`](#request) object, describing the query or + mutation to execute. + -#### Request +### Types -A Dgraph request object, used to execute queries and mutations. +#### Mutation + +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[] = []; +type Mutation struct { + SetJson string + DelJson string + SetNquads string + DelNquads string + Condition string } ``` - - Creates a new `Request` object with the given `query` and `mutations`. + + A JSON string representing the data to set in the mutation. + -The [`query`](#query) and [`mutations`](#mutation) fields are optional and -default to `null`. + + 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 Dgraph [`query`](#query) object. + + A string representing the data to delete in the mutation in NQuads format. - - An array of Dgraph [`mutation`](#mutation) objects. + + A string representing the condition query for the mutation. #### Query @@ -128,84 +134,35 @@ default to `null`. A Dgraph query object, used to execute queries. ```go -class Query { - constructor(query: string = "", variables: Variables = new Variables()); - query: string = ""; - variables: Map = new Map(); +type Query struct { + Query string + Variables map[string]string } ``` - - Creates a new `Query` object with the given `query` and `variables`. `query` - is a Dgraph Query Language (DQL) query string, and `variables` is a - [`Variables`](#variables) object. - - - + The DQL query to execute. - + A map of query variables. -#### Variables - -A Variables object used to set query variables in a Dgraph query. - -```go -class Variables { - public set(name: string, value: T): void; - public toMap(): Map; -} -``` - - - 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 +#### Request -A Dgraph mutation object, used to execute mutations. +A Dgraph request object, used to execute queries and mutations. ```go -class Mutation { - constructor( - public setJson: string = "", - public delJson: string = "", - public setNquads: string = "", - public delNquads: string = "", - public condition: string = "", - ) +type Request struct { + Query *Query + Mutations []*Mutation } ``` - - Creates a new `Mutation` object with the given `setJson`, `delJson`, - `setNquads`, `delNquads`, and `condition` fields. + + A pointer to a Dgraph [`query`](#query) object. - - 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. + + An slice of pointers to Dgraph [`mutation`](#mutation) objects. diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index 762e80c4..64b68dfd 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -12,7 +12,7 @@ GraphQL endpoint. ## Import -To begin, import the `graphql` namespace from the SDK: +To begin, import the `graphql` package from the SDK: ```go import github.com/hypermodeinc/modus/sdk/go/pkg/graphql @@ -22,44 +22,42 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/graphql {/* */} -The APIs in the `graphql` namespace are below, organized by category. +The APIs in the `graphql` package are below, organized by category. ### Functions -#### execute +#### Execute Execute a GraphQL statement to call a query or apply mutation against a GraphQL endpoint. ```go -graphql.execute ( - connection: string, - statement: string, - variables?: Variables -): Response +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. In AssemblyScript, create classes decorated with `@json`. + + 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. + -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). @@ -67,134 +65,99 @@ and maps. While it's possible to directly include parameter values into your GraphQL - statement, it's highly recommended to pass a [`Variables`](#variables) object - instead. This can help to prevent against injection attacks and other security - vulnerabilities. + 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. - -See the details of the [`Variables`](#variables) object for more information. - - - -### Objects - -#### 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. +Optional variables to include with the query. - - 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 can be of any type that's JSON serializable, including strings, -numbers, boolean values, arrays, maps, and custom objects decorated with -`@json`. +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. - - - Serializes the variables to a JSON string for inclusion in the GraphQL - operation. The `execute` function calls this automatically when you pass a - `Variables` object. You typically don't need to call it directly. - +### Types #### Response ```go -class Response { - errors: ErrorResult[] | null; - data: T | null; +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. +Either `Errors` or `Data` is present, depending on the result of the query. + + - - An array of errors incurred as part of your GraphQL request, if any. +An slice 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`. +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 has the type specified in the call to the `execute` function. If data -is absent due to errors, this field is `null`. +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 -class ErrorResult { - message: string; - locations: CodeLocation[] | null; - path: string[] | null; +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. + + +Path to the area of the GraphQL statement related to the error. -Each item in the array represents a segment of the path. +Each item in the slice represents a segment of the path. - - An array of [`CodeLocation`](#codelocation) objects that point to the specific + + An slice of [`CodeLocation`](#codelocation) objects that point to the specific location of the error in the GraphQL statement. #### CodeLocation ```go -class CodeLocation { - line: u32; - column: u32; +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 index ade31d3d..7ba6c898 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -12,10 +12,16 @@ 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. - - 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. +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 @@ -23,11 +29,11 @@ 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: +To begin, import the `http` package from the SDK: ```go import github.com/hypermodeinc/modus/sdk/go/pkg/http @@ -37,277 +43,404 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/http {/* */} -The APIs in the `http` namespace are below, organized by category. +The APIs in the `http` package are below, organized by category. ### Functions -#### fetch +#### Fetch Invoke an HTTP endpoint to retrieve data or trigger external action. Returns a [`Response`](#response) object with the HTTP response data. ```go -http.fetch( - requestOrUrl: string | Request, - options: RequestOptions = new RequestOptions(), -): Response +func Fetch[T *Request | string]( + requestOrUrl T, + options ...*RequestOptions +) (*Response, error) ``` - - Either a URL `string` or a [`Request`](#request) object, describing the HTTP request to make. + + +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. - + + 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. + + - - A [`RequestOptions`](#requestoptions) object with additional options for the - request, such as the HTTP method, headers, and body. + + An optional pointer to a [`RequestOptions`](#requestoptions) object with + additional options for the request, such as the HTTP method, headers, and + body. -### Objects +#### NewContent -#### Content +Creates a new [`Content`](#content) object from the given `value`, and returns a +pointer to it. ```go -class Content { - static from(value: any): Content; - readonly data: ArrayBuffer; - text(): string; - json(): T; -} +func NewContent(value any) *Content ``` -Represents content used in the body of an HTTP request or response. + + +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. - - Creates a new `Content` object from the given value. - - The raw binary content data. +#### 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 in the shape - of type `T`, and returns it as a value of type `T`. - + -#### Header +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 -class Header { - name: string; - values: string[]; +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 array of values for the header. Typically a header has a single value, but + + An slice of values for the header. Typically a header has a single value, but some headers can have multiple values. #### Headers -```go -class Headers { - static from( - value: string[][] | Map | Map, - ): 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. + + Use the [`NewHeaders`](#newheaders) function to create a new `Headers` object. + -The `value` object 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 - header values. -- A `Map`, where the keys are header names and the values are - arrays of header values. +```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 array contains a header name and + + Returns a `[][]string`, where each inner slice contains a header name and value. - - Returns the value of the header with the given `name`, or `null` if the header + + 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 -```go -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; -} -``` - Represents an HTTP request to make. - - Creates a new `Request` object with the given `url` and `options`. + + Use the [`NewRequest`](#newrequest) function to create a new `Request` object. + -The required `url` parameter must be a fully qualified URL of the request, -including the protocol. For example, `"https://example.com"`. - -The optional `options` parameter is a [`RequestOptions`](#requestoptions) object -that's used to set the HTTP method, headers, and body if needed. - - +```go +type Request struct { + Url string + Method string + Headers *Headers + Body []byte +} - - Creates a new `Request` object by cloning the given `request` and applying the - `options` to it. - +// 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 [`Headers`](#headers) object. + + The HTTP headers of the request, as a pointer to a [`Headers`](#headers) + object. - - The raw binary content data of the request body. + + +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. + + - - Interprets the request body as a UTF-8 encoded string, and returns it as a - `string` value. + + Clones the `Request` object, applies the `options` to the new object, and + returns it. - - Interprets the request body as a UTF-8 encoded string containing JSON in the - shape of type `T`, and returns it as a value of type `T`. + + Returns the binary content of the request body as a byte slice. -#### RequestOptions + + 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 -class RequestOptions { - method: string | null; - headers: Headers; - body: Content | null; +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 `null` (the default), the request uses the `GET` method. + `"DELETE"`. If empty, the request uses the `GET` method. - - The HTTP headers of the request, as a [`Headers`](#headers) object. + + +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. - - 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. + + +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. + - 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 -class Response { - readonly status: u16; - readonly statusText: string; - readonly headers: Headers; - readonly body: ArrayBuffer; - readonly ok: bool; - text(): string; - json(): T; +type Response struct { + Status uint16 + StatusText string + Headers *Headers + Body []byte } -``` -Represents the response received from the HTTP server. +// 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 [`Headers`](#headers) - object. + + 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 raw binary content data of the response body. + + + The response body isn't normally read directly. Instead, use the `Bytes`, + `Text`, or `JSON` methods. + + + - - 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. - + + Returns the binary content of the response body as a byte slice. - - Interprets the response body content 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, and + returns it as a `string` value. - - Interprets the response body content as a UTF-8 encoded string containing JSON - in the shape of type `T`, and returns it as a value of type `T`. + + +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/models.mdx b/modus/sdk/go/models.mdx index 0fe685f7..a4677bc2 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -11,13 +11,13 @@ 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. A common base class forms the core of the APIs, which -extends to conform to any model's required schema. +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 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 APIs are available in @@ -31,35 +31,18 @@ use it for any task that an AI model can perform. ## Import -To begin, import the `models` namespace from the SDK: +To begin, import the `models` package from the SDK: - - - ```go - import github.com/hypermodeinc/modus/sdk/go/pkg/models - ``` +```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: +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/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 { ClassificationModel } from "@hypermode/modus-sdk-as/models/experimental/classification" - ``` - - - +```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 @@ -69,23 +52,23 @@ a pull request, if you'd like to contribute a new model yourself. {/* */} -The APIs in the `models` namespace are below, organized by category. +The APIs in the `models` package are below, organized by category. ### Functions -#### getModel +#### GetModel Get a model instance by name and type. - ```go - models.getModel(modelName: string): T - ``` +```go +func GetModel[TModel](modelName string) (*TModel, error) +``` - - The type of model to return. This can be any class that extends the `Model` - base class. + + The type of model to return. This can be any struct that implements the + `Model` interface. @@ -93,85 +76,116 @@ 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 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. + -The base class for all models that Hypermode functions can invoke. +#### ModelBase + +The base type for all models that Modus functions can invoke. - If you are implementing a custom model, you should extend this class. You'll - also need classes 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. + 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 class. + 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 class. + returned by the model. It's usually a struct. - - 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 + + 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 - ```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. +available from a method on the `Model` interface. -This class relays information from the Modus runtime to the model +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 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. +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/neo4j.mdx b/modus/sdk/go/neo4j.mdx index 8872de9d..6e889cb3 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -12,7 +12,7 @@ database. ## Import -To begin, import the `neo4j` namespace from the SDK: +To begin, import the `neo4j` package from the SDK: ```go import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j @@ -22,97 +22,83 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j {/* */} -The APIs in the `neo4j` namespace are below, organized by category. +The APIs in the `neo4j` package are below, organized by category. ### Functions -#### executeQuery +#### ExecuteQuery -Execute a Neo4j query or mutation using a Neo4j query and parameters. +Executes a Cypher query on the Neo4j database. ```go -func ExecuteQuery(connectionName, query string, parameters map[string]any, opts ...Neo4jOption) (*EagerResult, error) +func ExecuteQuery( + connection, + query string, + parameters map[string]any, + opts ...Neo4jOption +) (*EagerResult, error) ``` - + Name of the connection, as [defined in the - manifest](../../app-manifest#connections). + manifest](/modus/app-manifest#connections). - A Neo4j query to execute. + 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. -#### GetRecordValue +#### GetProperty -Get the value of a record at a given key, and cast as a type. +Get a property from an entity at a given key and cast or decode it to a specific +type. ```go -func GetRecordValue[T RecordValue](record *Record, key string) (T, error) +func GetProperty[T PropertyValue](e Entity, key string) (T, error) ``` - - The record to get the value from. - - - - The key of the value to get. + + The type to cast or decode the value to. - - The type to cast the value as. + + The entity to get the value from. -#### 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 +#### GetRecordValue -Get the value of an `Entity` (`Node`, `Path`, or `Relationship`) property, and -cast as a type. +Get a value from a record at a given key and cast or decode it to a specific +type. ```go -func GetProperty[T PropertyValue](e Entity, key string) (T, error) +func GetRecordValue[T RecordValue](record *Record, key string) (T, error) ``` - - The entity to get the property from. + + The type to cast or decode the value to. - - The key of the property to get. + + The record to get the value from. - - The type to cast the property as. + + The key of the value to get. ### Types @@ -128,50 +114,17 @@ type EagerResult struct { } ``` - + 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. +An interface representing possible entities in a Neo4j query result. ```go type Entity interface { @@ -180,62 +133,44 @@ type Entity interface { } ``` + + 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 `json:"ElementId"` - Labels []string `json:"Labels"` - Props map[string]any `json:"Props"` + ElementId string + Labels []string + Props map[string]any } ``` - + 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. + + Returns the ID of the node. - - The type of the relationship. - - - - The properties of the relationship. + + Returns the properties of the node. #### Path @@ -244,30 +179,19 @@ A path in a Neo4j query result. ```go type Path struct { - Nodes []Node `json:"Nodes"` - Relationships []Relationship `json:"Relationships"` + Nodes []Node + Relationships []Relationship } ``` - + 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. @@ -280,15 +204,15 @@ type Point2D struct { } ``` - + The X coordinate of the point. - + The Y coordinate of the point. - + The spatial reference ID of the point. @@ -305,18 +229,114 @@ type Point3D struct { } ``` - + 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/postgresql.mdx b/modus/sdk/go/postgresql.mdx index 6964500f..33bee0ad 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -12,7 +12,7 @@ PostgreSQL-compatible database platform. ## Import -To begin, import the `postgresql` namespace from the SDK: +To begin, import the `postgresql` package from the SDK: ```go import github.com/hypermodeinc/modus/sdk/go/pkg/postgresql @@ -22,318 +22,265 @@ import github.com/hypermodeinc/modus/sdk/go/pkg/postgresql {/* */} -The APIs in the `postgresql` namespace are below, organized by category. +The APIs in the `postgresql` package are below, organized by category. ### Functions -#### execute +#### 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 + 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 + 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). ```go -function postgresql.execute ( - connectionName: string, - statement: string, - params?: Params -): Response +func Execute(connection, statement string, params ...any) (*db.Response, error) ``` - + 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. - - Optional parameters to include with the query. + + 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. + -See the details of the [`Params`](#params) object for more information. + + + Optional parameters to include with the query. -#### 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 -function postgresql.query( - connectionName: string, - statement: string, - params?: Params, -): QueryResponse +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. + + +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, +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](../../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. - - Optional parameters to include with the query. + + 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. + -See the details of the [`Params`](#params) object for more information. + + + Optional parameters to include with the query. -#### queryScalar +#### 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 -function postgresql.queryScalar ( - connectionName: string, - statement: string, - params?: Params -): ScalarResponse +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](../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 parameters as arguments instead. + This can help to protect 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 -### Objects +Represents a location on Earth, having `Longitude` and `Latitude` coordinates. -#### Params +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 -class Params { - public push(value: any): void; - public toJSON(): string; +type Location struct { + Longitude float64 + Latitude float64 } ``` -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. - - - 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 - statement, or you can pass a [`Point`](#point) or [`Location`](#location) - object as a single parameter. - - - + + The longitude coordinate of the location, in degrees. - - 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. + + The latitude coordinate of the location, in degrees. -#### Response +#### 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 -class Response { - error: string | null; - rowsAffected: u32; +type Point struct { + X float64 + Y float64 } ``` -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 +Represents the response from a [`Query`](#query) operation. + ```go -class QueryResponse { - error: string | null; - rowsAffected: u32; - rows: T[]; +type QueryResponse[T any] struct { + RowsAffected uint32 + LastInsertId uint64 + 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, which typically corresponds to + the number of rows returned. - - The number of rows affected by the operation. + + 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 array of objects, each representing a row returned from the query. Each + + An slice of objects, each representing a row returned from the query. Each object has fields corresponding to the columns in the result set. -#### ScalarResponse +#### Response + +Represents the response from an [`Execute`](#execute) operation. ```go -class ScalarResponse { - error: string | null; - rowsAffected: u32; - value: T; +type Response struct { + RowsAffected uint32 + LastInsertId uint64 } ``` -Represents the response from a [`queryScalar`](#queryscalar) operation. - - - 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. - - The number of rows affected by the operation. + + 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. - +#### ScalarResponse -#### Point +Represents the response from a [`QueryScalar`](#queryscalar) operation. ```go -class Point { - x: f64, - y: f64, +type ScalarResponse[T any] struct { + RowsAffected uint32 + LastInsertId uint64 + 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. + + The number of rows affected by the operation, which typically corresponds to + the number of rows returned. - - The y coordinate of the point. + + 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. -#### 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. - - - - The latitude coordinate of the location, in degrees. + + The scalar value returned from the query. diff --git a/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index ad2b27c6..0d8ed602 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -1,65 +1,72 @@ -agentic -alterSchema +[Aa]gentic +[Aa]lterSchema +[Bb]oolean +[Cc]ollections +[Cc]omputeDistance +[Cc]omputeSimilarity +[Cc]onsole +[Dd]eserialize +[Dd]graph +[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 +DQL +Errorf GitHub|github GraphiQL GraphQL|graphql gRPC -hardcoding HTTP|http Hugging Face -[Hh]yp -[Hh]ypercategories -[Hh]ypermode -inferencing -[Ll]og +Infof LLM -[Mm]odus -namespace -namespaces -nnClassify -npm +Logf +NPM|npm NQuads -onboarding -[Pp]arams PostgreSQL|postgresql PUT -queryScalar repo -REST +REST|[Rr]est Scattergories SDK|sdk -serializable -[Ss]erverless -timeEnd -triaging -upsert URL|url urql UUID -[Dd]eserialize -upsertBatch -computeDistance -getNamespaces -timeLog +Warnf From 4cd817a7cada416f08224b0b23e595b34cdccd40 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Wed, 29 Jan 2025 15:49:53 -0800 Subject: [PATCH 08/22] Add MySQL docs --- mint.json | 2 + modus/sdk/assemblyscript/mysql.mdx | 383 ++++++++++++++++++ modus/sdk/assemblyscript/postgresql.mdx | 6 +- modus/sdk/go/mysql.mdx | 281 +++++++++++++ modus/sdk/go/postgresql.mdx | 6 +- styles/config/vocabularies/general/accept.txt | 5 +- 6 files changed, 673 insertions(+), 10 deletions(-) create mode 100644 modus/sdk/assemblyscript/mysql.mdx create mode 100644 modus/sdk/go/mysql.mdx diff --git a/mint.json b/mint.json index 023bdb6b..63793611 100644 --- a/mint.json +++ b/mint.json @@ -118,6 +118,7 @@ "group": "Database APIs", "pages": [ "modus/sdk/assemblyscript/dgraph", + "modus/sdk/assemblyscript/mysql", "modus/sdk/assemblyscript/neo4j", "modus/sdk/assemblyscript/postgresql" ] @@ -147,6 +148,7 @@ "group": "Database APIs", "pages": [ "modus/sdk/go/dgraph", + "modus/sdk/go/mysql", "modus/sdk/go/neo4j", "modus/sdk/go/postgresql" ] diff --git a/modus/sdk/assemblyscript/mysql.mdx b/modus/sdk/assemblyscript/mysql.mdx new file mode 100644 index 00000000..21b58b06 --- /dev/null +++ b/modus/sdk/assemblyscript/mysql.mdx @@ -0,0 +1,383 @@ +--- +title: MySQL +description: "Execute queries against a MySQL database" +--- + +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.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/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index a6ef8a65..b1d85ae5 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -36,10 +36,8 @@ 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. ```ts diff --git a/modus/sdk/go/mysql.mdx b/modus/sdk/go/mysql.mdx new file mode 100644 index 00000000..12ef72da --- /dev/null +++ b/modus/sdk/go/mysql.mdx @@ -0,0 +1,281 @@ +--- +title: MySQL +description: "Execute queries against a MySQL database" +--- + +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.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/postgresql.mdx b/modus/sdk/go/postgresql.mdx index 33bee0ad..ff8fcd35 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -36,10 +36,8 @@ 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 diff --git a/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index 0d8ed602..1a2647b3 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -6,7 +6,6 @@ [Cc]omputeSimilarity [Cc]onsole [Dd]eserialize -[Dd]graph [Dd]istilbert [Dd]ropAll [Dd]ropAttr @@ -47,6 +46,7 @@ AWS CLI|cli CRUD Debugf +Dgraph DQL Errorf GitHub|github @@ -58,9 +58,10 @@ Hugging Face Infof LLM Logf +MySQL NPM|npm NQuads -PostgreSQL|postgresql +PostgreSQL PUT repo REST|[Rr]est From e57415f85ec6d0610886db34768ca785c9fa2b80 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Wed, 29 Jan 2025 16:02:34 -0800 Subject: [PATCH 09/22] Update manifest doc --- modus/app-manifest.mdx | 147 ++++++++++++------ styles/config/vocabularies/general/accept.txt | 7 +- 2 files changed, 102 insertions(+), 52 deletions(-) diff --git a/modus/app-manifest.mdx b/modus/app-manifest.mdx index 42b34948..99b863c0 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!** @@ -246,88 +247,83 @@ 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/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/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 @@ -366,6 +362,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/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/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index 1a2647b3..d4894f82 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -46,7 +46,7 @@ AWS CLI|cli CRUD Debugf -Dgraph +Dgraph|dgraph DQL Errorf GitHub|github @@ -58,15 +58,16 @@ Hugging Face Infof LLM Logf -MySQL +MySQL|mysql NPM|npm NQuads -PostgreSQL +PostgreSQL|postgresql PUT repo REST|[Rr]est Scattergories SDK|sdk +TLS URL|url urql UUID From 00ca15810afa9a7fa1527c3724e210c0833340f2 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Wed, 29 Jan 2025 17:04:24 -0800 Subject: [PATCH 10/22] Add localtime docs --- mint.json | 7 +- modus/sdk/assemblyscript/localtime.mdx | 133 ++++++++++++++++ modus/sdk/go/localtime.mdx | 146 ++++++++++++++++++ snippets/sdk-snippets.mdx | 3 +- styles/config/vocabularies/general/accept.txt | 4 + 5 files changed, 290 insertions(+), 3 deletions(-) create mode 100644 modus/sdk/assemblyscript/localtime.mdx create mode 100644 modus/sdk/go/localtime.mdx diff --git a/mint.json b/mint.json index 63793611..f66aa40b 100644 --- a/mint.json +++ b/mint.json @@ -133,7 +133,10 @@ }, { "group": "System APIs", - "pages": ["modus/sdk/assemblyscript/console"] + "pages": [ + "modus/sdk/assemblyscript/console", + "modus/sdk/assemblyscript/localtime" + ] } ] }, @@ -163,7 +166,7 @@ }, { "group": "System APIs", - "pages": ["modus/sdk/go/console"] + "pages": ["modus/sdk/go/console", "modus/sdk/go/localtime"] } ] } diff --git a/modus/sdk/assemblyscript/localtime.mdx b/modus/sdk/assemblyscript/localtime.mdx new file mode 100644 index 00000000..4097cef2 --- /dev/null +++ b/modus/sdk/assemblyscript/localtime.mdx @@ -0,0 +1,133 @@ +--- +title: Local Time +description: "Access the user's local time and time zone in your functions" +--- + +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.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/go/localtime.mdx b/modus/sdk/go/localtime.mdx new file mode 100644 index 00000000..b4cacce0 --- /dev/null +++ b/modus/sdk/go/localtime.mdx @@ -0,0 +1,146 @@ +--- +title: Local Time +description: "Access the user's local time and time zone in your functions" +--- + +import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.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/snippets/sdk-snippets.mdx b/snippets/sdk-snippets.mdx index 8dbb8f98..b612fb5b 100644 --- a/snippets/sdk-snippets.mdx +++ b/snippets/sdk-snippets.mdx @@ -5,6 +5,7 @@ export const SdkHeader = ({language, feature}) => (
    {(() =>{ const languages = ["AssemblyScript", "Go"]; + const page = feature.toLowerCase().replace(/\W/g, ""); return languages.map((lang) => { if (lang === language) { return ( @@ -12,7 +13,7 @@ export const SdkHeader = ({language, feature}) => ( ) } else { return ( -
  • {lang} {feature} APIs
    • +
  • {lang} {feature} APIs
    • ) } }) diff --git a/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index d4894f82..c8cfc586 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -55,7 +55,9 @@ GraphQL|graphql gRPC HTTP|http Hugging Face +IANA Infof +ISO LLM Logf MySQL|mysql @@ -69,6 +71,8 @@ Scattergories SDK|sdk TLS URL|url +UTC urql UUID Warnf +WASM From 2e86be2701d38049428d97ec6f965e8930798115 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Wed, 29 Jan 2025 17:16:29 -0800 Subject: [PATCH 11/22] update links --- getting-started-with-hyper-commerce.mdx | 18 +++++++++--------- modus/app-manifest.mdx | 22 +++++++++++++--------- 2 files changed, 22 insertions(+), 18 deletions(-) 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/modus/app-manifest.mdx b/modus/app-manifest.mdx index 99b863c0..1796af61 100644 --- a/modus/app-manifest.mdx +++ b/modus/app-manifest.mdx @@ -131,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:** @@ -250,7 +251,8 @@ This example specifies a query parameter named `key` provided by a secret named ### Dgraph 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. +[Dgraph APIs](/modus/sdk/assemblyscript/dgraph) in the Modus SDK to interact +with the database. **Example:** @@ -281,7 +283,8 @@ This connection type supports connecting to Dgraph databases. You can use the ### MySQL connection This connection type supports connecting to MySQL databases. You can use the -[MySQL APIs](/modus/sdk/mysql) in the Modus SDK to interact with the database. +[MySQL APIs](/modus/sdk/assemblyscript/mysql) in the Modus SDK to interact with +the database. **Example:** @@ -329,7 +332,8 @@ For example, use `tls=true` to enable encryption (not `sslmode=require`). ### 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:** @@ -365,8 +369,8 @@ This connection type supports connecting to Neo4j databases. You can use the ### PostgreSQL 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. +the [PostgreSQL APIs](/modus/sdk/assemblyscript/postgresql) in the Modus SDK to +interact with the database. **Example:** From 7a6a6fd109253c59da8ff730d8c64b37c24f7df9 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Wed, 29 Jan 2025 17:45:04 -0800 Subject: [PATCH 12/22] Update mint.json --- mint.json | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/mint.json b/mint.json index f66aa40b..43ec2a66 100644 --- a/mint.json +++ b/mint.json @@ -45,8 +45,44 @@ ], "redirects": [ { - "source": "/modus/sdk/:slug*", - "destination": "/modus/sdk/assemblyscript/:slug*" + "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": [ From a9495376fb0a7cc5f79bde4ff078dfc498c3ef38 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Wed, 29 Jan 2025 17:50:17 -0800 Subject: [PATCH 13/22] nit --- modus/sdk/assemblyscript/http.mdx | 2 +- modus/sdk/go/http.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index c6d2b1c7..e0230937 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -10,7 +10,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.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. diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index 7ba6c898..60eab30a 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -10,7 +10,7 @@ import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.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. 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 From 377b8c6a8998d265cfcf8ae5f073c831907de017 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 15:33:02 -0800 Subject: [PATCH 14/22] Adjust left nav --- mint.json | 84 +++++++----------------- modus/sdk/assemblyscript/collections.mdx | 5 +- modus/sdk/assemblyscript/console.mdx | 5 +- modus/sdk/assemblyscript/dgraph.mdx | 5 +- modus/sdk/assemblyscript/graphql.mdx | 5 +- modus/sdk/assemblyscript/http.mdx | 5 +- modus/sdk/assemblyscript/localtime.mdx | 5 +- modus/sdk/assemblyscript/models.mdx | 5 +- modus/sdk/assemblyscript/mysql.mdx | 5 +- modus/sdk/assemblyscript/neo4j.mdx | 5 +- modus/sdk/assemblyscript/overview.mdx | 6 ++ modus/sdk/assemblyscript/postgresql.mdx | 5 +- modus/sdk/go/collections.mdx | 5 +- modus/sdk/go/console.mdx | 5 +- modus/sdk/go/dgraph.mdx | 5 +- modus/sdk/go/graphql.mdx | 5 +- modus/sdk/go/http.mdx | 5 +- modus/sdk/go/localtime.mdx | 5 +- modus/sdk/go/models.mdx | 5 +- modus/sdk/go/mysql.mdx | 5 +- modus/sdk/go/neo4j.mdx | 5 +- modus/sdk/go/overview.mdx | 6 ++ modus/sdk/go/postgresql.mdx | 5 +- 23 files changed, 117 insertions(+), 79 deletions(-) create mode 100644 modus/sdk/assemblyscript/overview.mdx create mode 100644 modus/sdk/go/overview.mdx diff --git a/mint.json b/mint.json index 43ec2a66..1302b71d 100644 --- a/mint.json +++ b/mint.json @@ -138,72 +138,38 @@ "pages": ["modus/deepseek-model"] }, { - "group": "API Reference", + "group": "SDK Reference", "pages": [ { - "group": "AssemblyScript", + "group": "AssemblyScript SDK", "pages": [ - { - "group": "Client APIs", - "pages": [ - "modus/sdk/assemblyscript/graphql", - "modus/sdk/assemblyscript/http" - ] - }, - { - "group": "Database APIs", - "pages": [ - "modus/sdk/assemblyscript/dgraph", - "modus/sdk/assemblyscript/mysql", - "modus/sdk/assemblyscript/neo4j", - "modus/sdk/assemblyscript/postgresql" - ] - }, - { - "group": "Inference APIs", - "pages": ["modus/sdk/assemblyscript/models"] - }, - { - "group": "Storage APIs", - "pages": ["modus/sdk/assemblyscript/collections"] - }, - { - "group": "System APIs", - "pages": [ - "modus/sdk/assemblyscript/console", - "modus/sdk/assemblyscript/localtime" - ] - } + "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", + "group": "Go SDK", "pages": [ - { - "group": "Client APIs", - "pages": ["modus/sdk/go/graphql", "modus/sdk/go/http"] - }, - { - "group": "Database APIs", - "pages": [ - "modus/sdk/go/dgraph", - "modus/sdk/go/mysql", - "modus/sdk/go/neo4j", - "modus/sdk/go/postgresql" - ] - }, - { - "group": "Inference APIs", - "pages": ["modus/sdk/go/models"] - }, - { - "group": "Storage APIs", - "pages": ["modus/sdk/go/collections"] - }, - { - "group": "System APIs", - "pages": ["modus/sdk/go/console", "modus/sdk/go/localtime"] - } + "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/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index f8ee3c03..06d2aa2e 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -1,6 +1,9 @@ --- -title: Collections +title: "Collections APIs" +sidebarTitle: "Collections" description: "Add storage and vector search capabilities to your functions." +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index ae4b0c85..6dcbc657 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -1,6 +1,9 @@ --- -title: Console +title: "Console APIs" +sidebarTitle: "Console" description: "Capture errors and debugging information in your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 90ad0b54..0da1b90f 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -1,6 +1,9 @@ --- -title: Dgraph +title: "Dgraph APIs" +sidebarTitle: "Dgraph" description: "Execute queries and mutations against a Dgraph database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index c40aac23..157e4cdf 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -1,6 +1,9 @@ --- -title: GraphQL +title: "GraphQL APIs" +sidebarTitle: "GraphQL" description: "Access external GraphQL data sources from your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index e0230937..734d8046 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -1,6 +1,9 @@ --- -title: HTTP +title: "HTTP APIs" +sidebarTitle: "HTTP" description: "Access external HTTP endpoints from your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/localtime.mdx b/modus/sdk/assemblyscript/localtime.mdx index 4097cef2..f21621e6 100644 --- a/modus/sdk/assemblyscript/localtime.mdx +++ b/modus/sdk/assemblyscript/localtime.mdx @@ -1,6 +1,9 @@ --- -title: Local Time +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, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/models.mdx b/modus/sdk/assemblyscript/models.mdx index 4cf2d103..6ddbb135 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -1,6 +1,9 @@ --- -title: Models +title: "AI Model APIs" +sidebarTitle: "Models" description: "Invoke AI models from your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/mysql.mdx b/modus/sdk/assemblyscript/mysql.mdx index 21b58b06..52355cb2 100644 --- a/modus/sdk/assemblyscript/mysql.mdx +++ b/modus/sdk/assemblyscript/mysql.mdx @@ -1,6 +1,9 @@ --- -title: MySQL +title: "MySQL APIs" +sidebarTitle: "MySQL" description: "Execute queries against a MySQL database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index ab296ca3..a06e546f 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -1,6 +1,9 @@ --- -title: Neo4j +title: "Neo4j APIs" +sidebarTitle: "Neo4j" description: "Execute queries and mutations against a Neo4j database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/assemblyscript/overview.mdx b/modus/sdk/assemblyscript/overview.mdx new file mode 100644 index 00000000..44ea65f2 --- /dev/null +++ b/modus/sdk/assemblyscript/overview.mdx @@ -0,0 +1,6 @@ +--- +title: "Modus AssemblyScript SDK" +sidebarTitle: "Overview" +description: "Learn how to use the Modus AssemblyScript SDK" +icon: "circle-info" +--- diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index b1d85ae5..832776b0 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -1,6 +1,9 @@ --- -title: PostgreSQL +title: "PostgreSQL APIs" +sidebarTitle: "PostgreSQL" description: "Execute queries against a PostgreSQL database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index e2f84554..8ec61319 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -1,6 +1,9 @@ --- -title: Collections +title: "Collections APIs" +sidebarTitle: "Collections" description: "Add storage and vector search capabilities to your functions." +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index d173258a..31a11509 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -1,6 +1,9 @@ --- -title: Console +title: "Console APIs" +sidebarTitle: "Console" description: "Capture errors and debugging information in your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 27dfc420..5fbe8241 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -1,6 +1,9 @@ --- -title: Dgraph +title: "Dgraph APIs" +sidebarTitle: "Dgraph" description: "Execute queries and mutations against a Dgraph database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index 64b68dfd..09876331 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -1,6 +1,9 @@ --- -title: GraphQL +title: "GraphQL APIs" +sidebarTitle: "GraphQL" description: "Access external GraphQL data sources from your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index 60eab30a..f5fb8120 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -1,6 +1,9 @@ --- -title: HTTP +title: "HTTP APIs" +sidebarTitle: "HTTP" description: "Access external HTTP endpoints from your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/localtime.mdx b/modus/sdk/go/localtime.mdx index b4cacce0..dba71bad 100644 --- a/modus/sdk/go/localtime.mdx +++ b/modus/sdk/go/localtime.mdx @@ -1,6 +1,9 @@ --- -title: Local Time +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, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx index a4677bc2..25dacd28 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -1,6 +1,9 @@ --- -title: Models +title: "AI Model APIs" +sidebarTitle: "Models" description: "Invoke AI models from your functions" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/mysql.mdx b/modus/sdk/go/mysql.mdx index 12ef72da..917fb709 100644 --- a/modus/sdk/go/mysql.mdx +++ b/modus/sdk/go/mysql.mdx @@ -1,6 +1,9 @@ --- -title: MySQL +title: "MySQL APIs" +sidebarTitle: "MySQL" description: "Execute queries against a MySQL database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index 6e889cb3..3c35a35a 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -1,6 +1,9 @@ --- -title: Neo4j +title: "Neo4j APIs" +sidebarTitle: "Neo4j" description: "Execute queries and mutations against a Neo4j database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" diff --git a/modus/sdk/go/overview.mdx b/modus/sdk/go/overview.mdx new file mode 100644 index 00000000..a65e8ff6 --- /dev/null +++ b/modus/sdk/go/overview.mdx @@ -0,0 +1,6 @@ +--- +title: "Modus Go SDK" +sidebarTitle: "Overview" +description: "Learn how to use the Modus Go SDK" +icon: "circle-info" +--- diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index ff8fcd35..166252c4 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -1,6 +1,9 @@ --- -title: PostgreSQL +title: "PostgreSQL APIs" +sidebarTitle: "PostgreSQL" description: "Execute queries against a PostgreSQL database" +icon: "circle-small" +iconType: "solid" --- import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" From f1724ab7b07f2c06e51c18d1cfa428f18d7db051 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 16:41:17 -0800 Subject: [PATCH 15/22] Create overview pages for each SDK --- modus/sdk/assemblyscript/overview.mdx | 59 +++++++++++++++++++++++++++ modus/sdk/go/overview.mdx | 57 ++++++++++++++++++++++++++ snippets/sdk-overview-intro.mdx | 20 +++++++++ snippets/sdk-tip.mdx | 5 +++ 4 files changed, 141 insertions(+) create mode 100644 snippets/sdk-overview-intro.mdx create mode 100644 snippets/sdk-tip.mdx diff --git a/modus/sdk/assemblyscript/overview.mdx b/modus/sdk/assemblyscript/overview.mdx index 44ea65f2..383d26bb 100644 --- a/modus/sdk/assemblyscript/overview.mdx +++ b/modus/sdk/assemblyscript/overview.mdx @@ -4,3 +4,62 @@ 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/go/overview.mdx b/modus/sdk/go/overview.mdx index a65e8ff6..f0a78e65 100644 --- a/modus/sdk/go/overview.mdx +++ b/modus/sdk/go/overview.mdx @@ -4,3 +4,60 @@ 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/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! + From 17decc4cab4cc78d7a2b4c121c03c1eb55d023bb Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 16:42:26 -0800 Subject: [PATCH 16/22] fix go imports --- modus/sdk/go/collections.mdx | 2 +- modus/sdk/go/console.mdx | 2 +- modus/sdk/go/dgraph.mdx | 2 +- modus/sdk/go/graphql.mdx | 2 +- modus/sdk/go/http.mdx | 2 +- modus/sdk/go/localtime.mdx | 2 +- modus/sdk/go/models.mdx | 4 ++-- modus/sdk/go/mysql.mdx | 2 +- modus/sdk/go/neo4j.mdx | 2 +- modus/sdk/go/postgresql.mdx | 2 +- 10 files changed, 11 insertions(+), 11 deletions(-) diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index 8ec61319..97efa952 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -17,7 +17,7 @@ The Modus Collection APIs allow you to add vector search within your functions. To begin, import the `collections` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/collections +import "github.com/hypermodeinc/modus/sdk/go/pkg/collections" ``` ## Collections APIs diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index 31a11509..046ae126 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -34,7 +34,7 @@ captured and returned in the GraphQL response. To begin, import the `console` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/console +import "github.com/hypermodeinc/modus/sdk/go/pkg/console" ``` ## Console APIs diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 5fbe8241..b5be1b62 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -18,7 +18,7 @@ database. To begin, import the `dgraph` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/dgraph +import "github.com/hypermodeinc/modus/sdk/go/pkg/dgraph" ``` ## Dgraph APIs diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index 09876331..5be8c035 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -18,7 +18,7 @@ GraphQL endpoint. To begin, import the `graphql` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/graphql +import "github.com/hypermodeinc/modus/sdk/go/pkg/graphql" ``` ## GraphQL APIs diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index f5fb8120..9cf47a1b 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -39,7 +39,7 @@ repository, and aren't visible or accessible from your functions code. To begin, import the `http` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/http +import "github.com/hypermodeinc/modus/sdk/go/pkg/http" ``` ## HTTP APIs diff --git a/modus/sdk/go/localtime.mdx b/modus/sdk/go/localtime.mdx index dba71bad..dfe7ed30 100644 --- a/modus/sdk/go/localtime.mdx +++ b/modus/sdk/go/localtime.mdx @@ -18,7 +18,7 @@ zone from your functions. To begin, import the `localtime` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/localtime +import "github.com/hypermodeinc/modus/sdk/go/pkg/localtime" ``` {/* */} diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx index 25dacd28..f1261694 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -37,14 +37,14 @@ use it for any task that an AI model can perform. To begin, import the `models` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/models +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 +import "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai" ``` If you would like to request a new model, please diff --git a/modus/sdk/go/mysql.mdx b/modus/sdk/go/mysql.mdx index 917fb709..93d897cc 100644 --- a/modus/sdk/go/mysql.mdx +++ b/modus/sdk/go/mysql.mdx @@ -18,7 +18,7 @@ MySQL-compatible database platform. To begin, import the `mysql` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/mysql +import "github.com/hypermodeinc/modus/sdk/go/pkg/mysql" ``` ## MySQL APIs diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index 3c35a35a..f4aedf66 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -18,7 +18,7 @@ database. To begin, import the `neo4j` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/neo4j +import "github.com/hypermodeinc/modus/sdk/go/pkg/neo4j" ``` ## Neo4j APIs diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index 166252c4..f695504f 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -18,7 +18,7 @@ PostgreSQL-compatible database platform. To begin, import the `postgresql` package from the SDK: ```go -import github.com/hypermodeinc/modus/sdk/go/pkg/postgresql +import "github.com/hypermodeinc/modus/sdk/go/pkg/postgresql" ``` ## PostgreSQL APIs From d109dd7ad906209ed5b654762370ae0857857b4a Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 16:46:41 -0800 Subject: [PATCH 17/22] cleanup snippets --- modus/sdk/assemblyscript/collections.mdx | 3 ++- modus/sdk/assemblyscript/console.mdx | 3 ++- modus/sdk/assemblyscript/dgraph.mdx | 3 ++- modus/sdk/assemblyscript/graphql.mdx | 3 ++- modus/sdk/assemblyscript/http.mdx | 3 ++- modus/sdk/assemblyscript/localtime.mdx | 3 ++- modus/sdk/assemblyscript/models.mdx | 3 ++- modus/sdk/assemblyscript/mysql.mdx | 3 ++- modus/sdk/assemblyscript/neo4j.mdx | 3 ++- modus/sdk/assemblyscript/postgresql.mdx | 3 ++- modus/sdk/go/collections.mdx | 3 ++- modus/sdk/go/console.mdx | 3 ++- modus/sdk/go/dgraph.mdx | 3 ++- modus/sdk/go/graphql.mdx | 3 ++- modus/sdk/go/http.mdx | 3 ++- modus/sdk/go/localtime.mdx | 3 ++- modus/sdk/go/models.mdx | 3 ++- modus/sdk/go/mysql.mdx | 3 ++- modus/sdk/go/neo4j.mdx | 3 ++- modus/sdk/go/postgresql.mdx | 3 ++- snippets/sdk-snippets.mdx | 12 ------------ 21 files changed, 40 insertions(+), 32 deletions(-) diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index 06d2aa2e..9c8135e5 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index 6dcbc657..56ff83a6 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 0da1b90f..8a562837 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index 157e4cdf..76669a9b 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index 734d8046..dad487b8 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/localtime.mdx b/modus/sdk/assemblyscript/localtime.mdx index f21621e6..3d8204f7 100644 --- a/modus/sdk/assemblyscript/localtime.mdx +++ b/modus/sdk/assemblyscript/localtime.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/models.mdx b/modus/sdk/assemblyscript/models.mdx index 6ddbb135..ebbe48ae 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/mysql.mdx b/modus/sdk/assemblyscript/mysql.mdx index 52355cb2..833820b9 100644 --- a/modus/sdk/assemblyscript/mysql.mdx +++ b/modus/sdk/assemblyscript/mysql.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index a06e546f..0cab10bf 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index 832776b0..4200b8bc 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index 97efa952..7e3b1456 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index 046ae126..befb0623 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index b5be1b62..25e295bb 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index 5be8c035..f99123b0 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index 9cf47a1b..ffbfed97 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/localtime.mdx b/modus/sdk/go/localtime.mdx index dfe7ed30..f9eb2902 100644 --- a/modus/sdk/go/localtime.mdx +++ b/modus/sdk/go/localtime.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx index f1261694..1e642a09 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/mysql.mdx b/modus/sdk/go/mysql.mdx index 93d897cc..3272b293 100644 --- a/modus/sdk/go/mysql.mdx +++ b/modus/sdk/go/mysql.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index f4aedf66..c199c802 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index f695504f..5310735b 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -6,7 +6,8 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/snippets/sdk-snippets.mdx b/snippets/sdk-snippets.mdx index b612fb5b..5edef758 100644 --- a/snippets/sdk-snippets.mdx +++ b/snippets/sdk-snippets.mdx @@ -21,15 +21,3 @@ export const SdkHeader = ({language, feature}) => (
) - -export const SdkTip = () => ( - -

- We're constantly introducing new APIs through ongoing development with early users. - {" "} - Open an issue - {" "} - if you have ideas on what would make Modus even more powerful for your next app! -

- -) From 5f9faf836556088af9b66254d85e3d059cdf3584 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 16:47:38 -0800 Subject: [PATCH 18/22] . --- modus/sdk/assemblyscript/collections.mdx | 2 +- modus/sdk/assemblyscript/console.mdx | 2 +- modus/sdk/assemblyscript/dgraph.mdx | 2 +- modus/sdk/assemblyscript/graphql.mdx | 2 +- modus/sdk/assemblyscript/http.mdx | 2 +- modus/sdk/assemblyscript/localtime.mdx | 2 +- modus/sdk/assemblyscript/models.mdx | 2 +- modus/sdk/assemblyscript/mysql.mdx | 2 +- modus/sdk/assemblyscript/neo4j.mdx | 2 +- modus/sdk/assemblyscript/postgresql.mdx | 2 +- modus/sdk/go/collections.mdx | 2 +- modus/sdk/go/console.mdx | 2 +- modus/sdk/go/dgraph.mdx | 2 +- modus/sdk/go/graphql.mdx | 2 +- modus/sdk/go/http.mdx | 2 +- modus/sdk/go/localtime.mdx | 2 +- modus/sdk/go/models.mdx | 2 +- modus/sdk/go/mysql.mdx | 2 +- modus/sdk/go/neo4j.mdx | 2 +- modus/sdk/go/postgresql.mdx | 2 +- snippets/{sdk-snippets.mdx => sdk-header.mdx} | 0 21 files changed, 20 insertions(+), 20 deletions(-) rename snippets/{sdk-snippets.mdx => sdk-header.mdx} (100%) diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx index 9c8135e5..9974285f 100644 --- a/modus/sdk/assemblyscript/collections.mdx +++ b/modus/sdk/assemblyscript/collections.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/console.mdx b/modus/sdk/assemblyscript/console.mdx index 56ff83a6..3a6c34cb 100644 --- a/modus/sdk/assemblyscript/console.mdx +++ b/modus/sdk/assemblyscript/console.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/dgraph.mdx b/modus/sdk/assemblyscript/dgraph.mdx index 8a562837..aacff039 100644 --- a/modus/sdk/assemblyscript/dgraph.mdx +++ b/modus/sdk/assemblyscript/dgraph.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index 76669a9b..da253dcd 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/http.mdx b/modus/sdk/assemblyscript/http.mdx index dad487b8..ca8e76b2 100644 --- a/modus/sdk/assemblyscript/http.mdx +++ b/modus/sdk/assemblyscript/http.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/localtime.mdx b/modus/sdk/assemblyscript/localtime.mdx index 3d8204f7..a2565727 100644 --- a/modus/sdk/assemblyscript/localtime.mdx +++ b/modus/sdk/assemblyscript/localtime.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/models.mdx b/modus/sdk/assemblyscript/models.mdx index ebbe48ae..127b1251 100644 --- a/modus/sdk/assemblyscript/models.mdx +++ b/modus/sdk/assemblyscript/models.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/mysql.mdx b/modus/sdk/assemblyscript/mysql.mdx index 833820b9..baa21343 100644 --- a/modus/sdk/assemblyscript/mysql.mdx +++ b/modus/sdk/assemblyscript/mysql.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/neo4j.mdx b/modus/sdk/assemblyscript/neo4j.mdx index 0cab10bf..39d33da5 100644 --- a/modus/sdk/assemblyscript/neo4j.mdx +++ b/modus/sdk/assemblyscript/neo4j.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/assemblyscript/postgresql.mdx b/modus/sdk/assemblyscript/postgresql.mdx index 4200b8bc..d6b46a71 100644 --- a/modus/sdk/assemblyscript/postgresql.mdx +++ b/modus/sdk/assemblyscript/postgresql.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx index 7e3b1456..58232cda 100644 --- a/modus/sdk/go/collections.mdx +++ b/modus/sdk/go/collections.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/console.mdx b/modus/sdk/go/console.mdx index befb0623..65b64ee4 100644 --- a/modus/sdk/go/console.mdx +++ b/modus/sdk/go/console.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/dgraph.mdx b/modus/sdk/go/dgraph.mdx index 25e295bb..b0cd9140 100644 --- a/modus/sdk/go/dgraph.mdx +++ b/modus/sdk/go/dgraph.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/graphql.mdx b/modus/sdk/go/graphql.mdx index f99123b0..1d80466b 100644 --- a/modus/sdk/go/graphql.mdx +++ b/modus/sdk/go/graphql.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/http.mdx b/modus/sdk/go/http.mdx index ffbfed97..3da84c6f 100644 --- a/modus/sdk/go/http.mdx +++ b/modus/sdk/go/http.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/localtime.mdx b/modus/sdk/go/localtime.mdx index f9eb2902..f1c9bc23 100644 --- a/modus/sdk/go/localtime.mdx +++ b/modus/sdk/go/localtime.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/models.mdx b/modus/sdk/go/models.mdx index 1e642a09..81442e8d 100644 --- a/modus/sdk/go/models.mdx +++ b/modus/sdk/go/models.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/mysql.mdx b/modus/sdk/go/mysql.mdx index 3272b293..5a44818e 100644 --- a/modus/sdk/go/mysql.mdx +++ b/modus/sdk/go/mysql.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/neo4j.mdx b/modus/sdk/go/neo4j.mdx index c199c802..0e390c78 100644 --- a/modus/sdk/go/neo4j.mdx +++ b/modus/sdk/go/neo4j.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/modus/sdk/go/postgresql.mdx b/modus/sdk/go/postgresql.mdx index 5310735b..00f08f14 100644 --- a/modus/sdk/go/postgresql.mdx +++ b/modus/sdk/go/postgresql.mdx @@ -6,7 +6,7 @@ icon: "circle-small" iconType: "solid" --- -import { SdkHeader } from "/snippets/sdk-snippets.mdx" +import { SdkHeader } from "/snippets/sdk-header.mdx" import SdkTip from "/snippets/sdk-tip.mdx" diff --git a/snippets/sdk-snippets.mdx b/snippets/sdk-header.mdx similarity index 100% rename from snippets/sdk-snippets.mdx rename to snippets/sdk-header.mdx From bc5821c2007defc8e630250d9f20a43c19a485ae Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 17:11:46 -0800 Subject: [PATCH 19/22] Update change log page --- modus/changelog.mdx | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) 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! From 2e035d47812322a9e8217d23d9e94c8557c05746 Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 17:13:02 -0800 Subject: [PATCH 20/22] nit --- introduction.mdx | 2 -- 1 file changed, 2 deletions(-) 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 From c5237f0c112c2731acf8a7691e52b662d90af5de Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Thu, 30 Jan 2025 17:15:19 -0800 Subject: [PATCH 21/22] nit --- modus/overview.mdx | 2 -- 1 file changed, 2 deletions(-) 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, From bd0a4196418c6f57fcdc010d078ec4870b9a6dbb Mon Sep 17 00:00:00 2001 From: Matt Johnson-Pint Date: Fri, 31 Jan 2025 07:56:55 -0800 Subject: [PATCH 22/22] . --- modus/sdk/assemblyscript/graphql.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modus/sdk/assemblyscript/graphql.mdx b/modus/sdk/assemblyscript/graphql.mdx index da253dcd..59e357d5 100644 --- a/modus/sdk/assemblyscript/graphql.mdx +++ b/modus/sdk/assemblyscript/graphql.mdx @@ -19,7 +19,7 @@ GraphQL endpoint. To begin, import the `graphql` namespace from the SDK: ```ts -import { http } from "@hypermode/modus-sdk-as" +import { graphql } from "@hypermode/modus-sdk-as" ``` ## GraphQL APIs