From 157c9fe3f6bb14286e9b3d3ff90d3af2bd5aa95a Mon Sep 17 00:00:00 2001 From: 0xSage Date: Fri, 27 Oct 2023 15:50:49 +0700 Subject: [PATCH] docs: more ref examples --- docs/docs/reference/03_events.md | 35 +++++++++++++++ docs/docs/reference/04_store.md | 61 +++++++++++++++++++++++++++ docs/docs/reference/05_filesystem.md | 22 ++++++++-- docs/docs/reference/06_preferences.md | 44 ++++++++++++++++++- 4 files changed, 157 insertions(+), 5 deletions(-) diff --git a/docs/docs/reference/03_events.md b/docs/docs/reference/03_events.md index b86084cdc..0e0c8104d 100644 --- a/docs/docs/reference/03_events.md +++ b/docs/docs/reference/03_events.md @@ -12,6 +12,41 @@ You can then implement custom logic handlers for such events. import { events } from "@janhq/core"; ``` +You can subscribe to NewMessageRequest events by defining a function to handle the event and registering it with the events object: + +```js +import { events } from "@janhq/core"; + +function handleMessageRequest(message: NewMessageRequest) { + // Your logic here. For example: + // const response = openai.createChatCompletion({...}) +} +function registerListener() { + events.on(EventName.OnNewMessageRequest, handleMessageRequest); +} +// Register the listener function with the relevant extension points. +export function init({ register }) { + registerListener(); +} +``` + +In this example, we're defining a function called handleMessageRequest that takes a NewMessageRequest object as its argument. We're also defining a function called registerListener that registers the handleMessageRequest function as a listener for NewMessageRequest events using the on method of the events object. + +```js +import { events } from "@janhq/core"; + +function handleMessageRequest(data: NewMessageRequest) { + // Your logic here. For example: + const response = openai.createChatCompletion({...}) + const message: NewMessageResponse = { + ...data, + message: response.data.choices[0].message.content + } + // Now emit event so the app can display in the conversation + events.emit(EventName.OnNewMessageResponse, message) +} +``` + ## EventName The `EventName` enum bundles the following events: diff --git a/docs/docs/reference/04_store.md b/docs/docs/reference/04_store.md index 3dc7c6a5e..5da2ee15a 100644 --- a/docs/docs/reference/04_store.md +++ b/docs/docs/reference/04_store.md @@ -13,3 +13,64 @@ _Note: default `store` logic is from [@data-plugin](https://www.npmjs.com/packag ```js import { store } from "@janhq/core"; ``` + +## Insert Data + +You can use the store.insertOne function to insert data into a specific collection in the local data store. + +```js +import { store } from "@janhq/core"; + +function insertData() { + store.insertOne("conversations", { name: "meow" }); + // Insert a new document with { name: "meow" } into the "conversations" collection. +} +``` + +## Get Data + +To retrieve data from a collection in the local data store, you can use the `store.findOne` or `store.findMany` function. It allows you to filter and retrieve documents based on specific criteria. + +store.getOne(collectionName, key) retrieves a single document that matches the provided key in the specified collection. +store.getMany(collectionName, selector, sort) retrieves multiple documents that match the provided selector in the specified collection. + +```js +import { store } from "@janhq/core"; + +function getData() { + const selector = { name: "meow" }; + const data = store.findMany("conversations", selector); + // Retrieve documents from the "conversations" collection that match the filter. +} +``` + +## Update Data + +You can update data in the local store using these functions: + +store.updateOne(collectionName, key, update) updates a single document that matches the provided key in the specified collection. +store.updateMany(collectionName, selector, update) updates multiple documents that match the provided selector in the specified collection. + +```js +function updateData() { + const selector = { name: "meow" }; + const update = { name: "newName" }; + store.updateOne("conversations", selector, update); + // Update a document in the "conversations" collection. +} +``` + +## Delete Data + +You can delete data from the local data store using these functions: + +store.deleteOne(collectionName, key) deletes a single document that matches the provided key in the specified collection. +store.deleteMany(collectionName, selector) deletes multiple documents that match the provided selector in the specified collection. + +```js +function deleteData() { + const selector = { name: "meow" }; + store.deleteOne("conversations", selector); + // Delete a document from the "conversations" collection. +} +``` diff --git a/docs/docs/reference/05_filesystem.md b/docs/docs/reference/05_filesystem.md index 3583492a7..baa1fa30a 100644 --- a/docs/docs/reference/05_filesystem.md +++ b/docs/docs/reference/05_filesystem.md @@ -2,7 +2,7 @@ title: "filesystem" --- -The Core API also provides functions to perform file operations. Here are a couple of examples: +The core package also provides functions to perform file operations. Here are a couple of examples: ## Usage @@ -14,6 +14,22 @@ const core = require("@janhq/core"); import * as core from "@janhq/core"; ``` -## downloadFile +## Download a File -## deleteFile +You can download a file from a specified URL and save it with a given file name using the core.downloadFile function. + +```js +function downloadModel(url: string, fileName: string) { + core.downloadFile(url, fileName); +} +``` + +## Delete a File + +To delete a file, you can use the core.deleteFile function, providing the path to the file you want to delete. + +```js +function deleteModel(filePath: string) { + core.deleteFile(path); +} +``` diff --git a/docs/docs/reference/06_preferences.md b/docs/docs/reference/06_preferences.md index 1f00879b9..15e72e57d 100644 --- a/docs/docs/reference/06_preferences.md +++ b/docs/docs/reference/06_preferences.md @@ -2,12 +2,52 @@ title: "preferences" --- -`preferences` is a helper object for adding settings fields to your apps. +`preferences` is a helper object for adding settings fields to your app. ## Usage +To register plugin preferences, you can use the preferences object from the @janhq/core package. Here's an example of how to register and retrieve plugin preferences: + ```js -todo; +import { PluginService, preferences } from "@janhq/core"; + +const pluginName = "your-first-plugin"; +const preferenceKey = ""; +const preferenceName = "Your First Preference"; +const preferenceDescription = "This is for example only"; +const defaultValue = ""; + +export function init({ register }: { register: RegisterExtensionPoint }) { + // Register preference update handlers. E.g. update plugin instance with new configuration + register(PluginService.OnPreferencesUpdate, pluginName, onPreferencesUpdate); + + // Register plugin preferences. E.g. Plugin need apiKey to connect to your service + preferences.registerPreferences < + string > + (register, + pluginName, + preferenceKey, + preferenceName, + preferenceDescription, + defaultValue); +} +``` + +In this example, we're registering preference update handlers and plugin preferences using the preferences object. We're also defining a PluginName constant to use as the name of the plugin. + +To retrieve the values of the registered preferences, we're using the get method of the preferences object and passing in the name of the plugin and the name of the preference. + +```js +import { preferences } from "@janhq/core"; + +const pluginName = "your-first-plugin"; +const preferenceKey = "apiKey"; + +const setup = async () => { + // Retrieve apiKey + const apiKey: string = + (await preferences.get(pluginName, preferenceKey)) ?? ""; +}; ``` ## registerPreferences