From 08605c7ab29d83459d5328eeaa1d308bb0d2e4c5 Mon Sep 17 00:00:00 2001 From: Tommaso Allevi Date: Thu, 14 Sep 2023 12:19:02 +0200 Subject: [PATCH] Add docs --- packages/docs/pages/_meta.json | 4 + packages/docs/pages/index.mdx | 141 +++++++++++++---------- packages/docs/pages/usage/_meta.json | 3 +- packages/docs/pages/usage/create.mdx | 2 +- packages/docs/pages/usage/typescript.mdx | 49 ++++++++ 5 files changed, 138 insertions(+), 61 deletions(-) create mode 100644 packages/docs/pages/usage/typescript.mdx diff --git a/packages/docs/pages/_meta.json b/packages/docs/pages/_meta.json index 20d7253b3..5b2f0e0c5 100644 --- a/packages/docs/pages/_meta.json +++ b/packages/docs/pages/_meta.json @@ -26,6 +26,10 @@ "filters": { "title": "Filters", "href": "/usage/search/filters" + }, + "typescript": { + "title": "Typescript", + "href": "/usage/typescript" } } }, diff --git a/packages/docs/pages/index.mdx b/packages/docs/pages/index.mdx index 13e746904..785295cf7 100644 --- a/packages/docs/pages/index.mdx +++ b/packages/docs/pages/index.mdx @@ -1,4 +1,4 @@ -import { Tab, Tabs, Card, Cards } from 'nextra-theme-docs' +import { Tab, Tabs, Card, Cards, Callout } from 'nextra-theme-docs' import { BsDatabaseFillAdd, BsCodeSlash, BsPlugin } from 'react-icons/bs' import { AiFillFileAdd, AiOutlineSearch, AiFillDelete } from 'react-icons/ai' @@ -19,40 +19,6 @@ Orama is a fast, batteries-included, full-text and vector search engine entirely Get started with just a few lines of code: - - } - title="Create a new database" - href="/usage/create" - /> - } - title="Insert data" - href="/usage/insert" - /> - } - title="Search" - href="/usage/search/introduction" - /> - } - title="Remove data" - href="/usage/remove" - /> - } - title="Extend Orama" - href="/internals/components" - /> - } - title="Use Plugins" - href="/plugins" - /> - - - ## Requirements @@ -62,7 +28,7 @@ A JavaScript runtime is the **only** requirement. Orama has been designed to wor You can install Orama using npm, yarn, pnpm: - + ```bash copy npm install @orama/orama @@ -78,40 +44,97 @@ You can install Orama using npm, yarn, pnpm: pnpm add @orama/orama ``` + + ```html copy + + + + + + ``` + -Or import it directly in a browser module: - -```html copy - - - - - +```js copy +import { create, insert, search } from '@orama/orama' ``` -# CommonJS Imports + + Orama ships **ESM** modules by default. This allows us to move faster when providing new features and bug fixes, as well as using the `"exports"` field in `package.json` to provide a better developer experience. + CommonJS imports are still supported, but we suggest you to migrate to ESM. + -Orama ships **ESM** modules by default. This allows us to move faster when providing new features and bug fixes, as well as using the `"exports"` field in `package.json` to provide a better developer experience. +## Usage -CommonJS imports are still supported, but we suggest you to migrate to ESM. +```js copy +import { create, insert, search } from '@orama/orama' -## TypeScript - -Set `moduleResolution` in the `compilerOptions` in your `tsconfig.json` to be either `Node16` or `NodeNext`. - -When importing types, always refer to the standard orama import: +const db = await create({ + schema: { + title: 'string', + description: 'string', + } +}); +await insert(db, { title: 'foo', description: 'bar' }); +const results = await search(db, { term: 'foo' }); +``` -```ts copy -import type { Language } from '@orama/orama' +The variable `results` will contain the following object: +```js +{ + elapsed: { raw: 924798, formatted: '924μs' }, + count: 1, + hits: [ + { + id: '84747683-1', + score: 0.3530643616453674, + document: { title: 'foo', description: 'bar' } + } + ] +} ``` -# Community Rewards + + } + title="Create a new database" + href="/usage/create" + /> + } + title="Insert data" + href="/usage/insert" + /> + } + title="Search" + href="/usage/search/introduction" + /> + } + title="Remove data" + href="/usage/remove" + /> + } + title="Extend Orama" + href="/internals/components" + /> + } + title="Use Plugins" + href="/plugins" + /> + + +## Community Rewards +Are you using Orama in production? Have you written an article or made a YouTube video on Orama? [Contact us](mailto:info@oramasearch.com) to get some Orama swag in return! ![Orama Community Rewards](/misc/community-rewards.png) -Are you using Orama in production? Have you written an article or made a YouTube video on Orama? [Contact us](mailto:info@oramasearch.com) to get some Orama swag in return! diff --git a/packages/docs/pages/usage/_meta.json b/packages/docs/pages/usage/_meta.json index f6a2b9021..d74a06451 100644 --- a/packages/docs/pages/usage/_meta.json +++ b/packages/docs/pages/usage/_meta.json @@ -4,5 +4,6 @@ "remove": "Remove", "update": "Update", "utilities": "Utilities", - "search": "Search" + "search": "Search", + "typescript": "Typescript" } diff --git a/packages/docs/pages/usage/create.mdx b/packages/docs/pages/usage/create.mdx index 927aabbe9..ef4bbc194 100644 --- a/packages/docs/pages/usage/create.mdx +++ b/packages/docs/pages/usage/create.mdx @@ -9,7 +9,7 @@ Not all properties need to be indexed, but only those that we want to be able to Adding a property to the schema will make it searchable, but it will also increase the size of the database and overall insertion and search times. -Therefore, you should only index the properties that you need to search for. +Therefore, for having a better experience, you should only index the properties that you need to search for. If you want to learn more and see real-world examples, check out [this blog post](https://oramasearch.com/blog/optimizing-orama-schema-optimization) we wrote about schema optimization. diff --git a/packages/docs/pages/usage/typescript.mdx b/packages/docs/pages/usage/typescript.mdx new file mode 100644 index 000000000..1c52dcbc6 --- /dev/null +++ b/packages/docs/pages/usage/typescript.mdx @@ -0,0 +1,49 @@ + + +# TypeScript + +## Configuration +Set `moduleResolution` in the `compilerOptions` in your `tsconfig.json` to be either `Node16` or `NodeNext`. + +When importing types, always refer to the standard orama import: + +```ts copy +import type { Language } from '@orama/orama' +``` + +## Usage + +Orama is written in TypeScript and provides type definitions for all of its public APIs. +This means the results of all functions are typed, and the types are **inferred from the schema provided**. + +```typescript copy +const db = await create({ + schema: { + title: 'string', + plot: 'string', + } +}) +await insert(db, { + title: 'The prestige', + plot: 'Two friends and fellow magicians become bitter enemies after a sudden tragedy. As they devote themselves to this rivalry, they make sacrifices that bring them fame but with terrible consequences.' +}) +const s = await search(db, { term: 'prestige' }) + +const firstTitle: string = s.hits[0].document.title // Inferred by the schema provided +``` + +Anyway, because Orama schema defines only searchable fields, you may want to add some extra fields to your documents. +Extra fields are not indexed, so they are not searchable, but they are still available in the results. +The type of these fields is not inferred, so it's `any`. + +```typescript copy +await insert(db, { + title: 'Big Fish', + director: 'Tim Burton', + plot: 'Will Bloom returns home to care for his dying father, who had a penchant for telling unbelievable stories. After he passes away, Will tries to find out if his tales were really true.', + year: 2004, + isFavorite: true +}) +const s = await search(db, { term: 'fish' }) +const year: any = s.hits[0].document.year // not inferred, so it's any +```