Add docs

oramasearch · Sep 14, 2023 · 08605c7 · 08605c7
1 parent 682a3e8
commit 08605c7
Show file tree

Hide file tree

Showing 5 changed files with 138 additions and 61 deletions.
diff --git 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
@@ -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:
 
-<Cards>
-  <Card
-    icon={<BsDatabaseFillAdd style={{ width: 22, height: 22 }} />}
-    title="Create a new database"
-    href="/usage/create"
-  />
-  <Card
-    icon={<AiFillFileAdd style={{ width: 22, height: 22 }} />}
-    title="Insert data"
-    href="/usage/insert"
-  />
-  <Card
-    icon={<AiOutlineSearch style={{ width: 22, height: 22 }} />}
-    title="Search"
-    href="/usage/search/introduction"
-  />
-  <Card
-    icon={<AiFillDelete style={{ width: 22, height: 22 }} />}
-    title="Remove data"
-    href="/usage/remove"
-  />
-  <Card
-    icon={<BsCodeSlash style={{ width: 22, height: 22 }} />}
-    title="Extend Orama"
-    href="/internals/components"
-  />
-  <Card
-    icon={<BsPlugin style={{ width: 22, height: 22 }} />}
-    title="Use Plugins"
-    href="/plugins"
-  />
-</Cards>
-
-
 
 ## 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:
 
-<Tabs items={['npm', 'yarn', 'pnpm']}>
+<Tabs items={['npm', 'yarn', 'pnpm', 'unpkg']}>
   <Tab>
     ```bash copy 
     npm install @orama/orama 
@@ -78,40 +44,97 @@ You can install Orama using npm, yarn, pnpm:
     pnpm add @orama/orama 
     ```
   </Tab>
+  <Tab>
+    ```html copy
+    <html>
+      <body>
+        <script type="module">
+          import { create, search, insert } from 'https://unpkg.com/@orama/orama@latest/dist/index.js'
+
+          // ...
+        </script>
+      </body>
+    </html>
+    ```
+  </Tab>
 </Tabs>
 
-Or import it directly in a browser module:
-
-```html copy
-<html>
-  <body>
-    <script type="module">
-      import { create, search, insert } from 'https://unpkg.com/@orama/orama@latest/dist/index.js'
+## Import
 
-      // ...
-    </script>
-  </body>
-</html>
+```js copy
+import { create, insert, search } from '@orama/orama'
 ```
 
-# CommonJS Imports
+<Callout type="info">
+  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.
+</Callout>
 
-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
+<Cards>
+  <Card
+    icon={<BsDatabaseFillAdd style={{ width: 22, height: 22 }} />}
+    title="Create a new database"
+    href="/usage/create"
+  />
+  <Card
+    icon={<AiFillFileAdd style={{ width: 22, height: 22 }} />}
+    title="Insert data"
+    href="/usage/insert"
+  />
+  <Card
+    icon={<AiOutlineSearch style={{ width: 22, height: 22 }} />}
+    title="Search"
+    href="/usage/search/introduction"
+  />
+  <Card
+    icon={<AiFillDelete style={{ width: 22, height: 22 }} />}
+    title="Remove data"
+    href="/usage/remove"
+  />
+  <Card
+    icon={<BsCodeSlash style={{ width: 22, height: 22 }} />}
+    title="Extend Orama"
+    href="/internals/components"
+  />
+  <Card
+    icon={<BsPlugin style={{ width: 22, height: 22 }} />}
+    title="Use Plugins"
+    href="/plugins"
+  />
+</Cards>
+
+## 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
@@ -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
@@ -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
@@ -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
+```