refactor: review typescript signature (#164)

README.md

@@ -202,6 +202,58 @@ app.get('/genId', async function handler (req, reply) {
 })
 ```
 
+## Typescript
+
+This plugin comes with Typescript support out of the box.
+Using the `withOrama` helper, you can access the `orama` decorator in your Fastify application with the correct schema.
+
+```ts
+import Fastify from 'fastify'
+
+import { PersistenceInMemory, fastifyOrama } from 'fastify-orama'
+
+const app = Fastify()
+
+const mySchema = {
+  quote: 'string',
+  author: 'string'
+} as const
+
+await app.register(fastifyOrama, {
+  schema: mySchema,
+  persistence: new PersistenceInMemory()
+})
+
+const appWithOrama = app.withOrama<typeof mySchema>()
+const id = await appWithOrama.orama.insert({ quote: 'Hello', author: 'World' })
+
+appWithOrama.get('/hello', async () => {
+
+  const {orama} = appWithOrama
+  const result = await orama.search({ term: 'hello' })
+
+  return {
+    hello: result.hits
+  }
+})
+```
+
+Usage with `fastify-plugin`:
+
+```ts
+import fp from 'fastify-plugin'
+
+fp(function plugins(fastify) {
+  const fastifyWithOrama = fastify.withOrama<typeof mySchema>()
+
+  expectType<{
+    insert: (document: PartialSchemaDeep<TypedDocument<Orama<typeof mySchema>>>) => Promise<string>,
+    search: (params: SearchParams<Orama<Schema<typeof mySchema>>, typeof mySchema>) => Promise<Results<Schema<typeof mySchema>>>,
+    persist?: () => Promise<any>,
+  }>(fastifyWithOrama.orama)
+})
+```
+
 ## License
 
 fastifyOrama is licensed under the [MIT](LICENSE) license.

index.d.ts

@@ -31,13 +31,17 @@ type FastifyOramaPluginOptions = {
 
 declare const fastifyOrama: FastifyPluginCallback<FastifyOramaPluginOptions>
 
+interface OramaApi<T> {
+  insert: (document: PartialSchemaDeep<TypedDocument<Orama<T>>>) => Promise<string>,
+  search: (params: SearchParams<Orama<Schema<T>>, T>) => Promise<Results<Schema<T>>>,
+  persist?: () => Promise<any>,
+}
+
 declare module 'fastify' {
   interface FastifyInstance {
-    getOrama<T>(): {
-      insert: (document: PartialSchemaDeep<TypedDocument<Orama<T>>>) => Promise<string>,
-      search: (params: SearchParams<Orama<Schema<T>>, T>) => Promise<Results<Schema<T>>>,
-      persist?: () => Promise<any>,
-    }
+    withOrama<T>(): this & {
+      orama: OramaApi<T>
+    };
   }
 }
 

index.js

@@ -51,10 +51,12 @@ async function fastifyOrama (fastify, options) {
     db = await Orama.create(oramaOptions)
   }
 
+  function withOrama () {
+    return this
+  }
+
   fastify.decorate('orama', oramaApi)
-  fastify.decorate('getOrama', function () {
-    return oramaApi
-  })
+  fastify.decorate('withOrama', withOrama)
 }
 
 module.exports = fp(fastifyOrama, {

package.json

@@ -13,7 +13,7 @@
     "lint": "standard | snazzy",
     "lint:fix": "standard --fix | snazzy",
     "pretest": "npm run clean",
-    "test": "npm run lint && npm run unit && npm run typescript",
+    "test": "npm run lint && npm run unit && npm run typescript && ts-node test/types/index.ts",
     "posttest": "npm run clean",
     "typescript": "tsd",
     "prepare": "husky install",
@@ -50,10 +50,14 @@
     "husky": "^8.0.3",
     "snazzy": "^9.0.0",
     "standard": "^17.1.0",
+    "ts-node": "^10.9.1",
     "tsd": "^0.29.0",
     "typescript": "^5.2.2"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "tsd": {
+    "directory": "test/types"
   }
 }

test/index.test.js

@@ -73,7 +73,7 @@ it('Should throw when trying to register multiple instances without giving a nam
   }
 })
 
-it('Expose a getOrama function', async () => {
+it('Expose a withOrama function', async () => {
   const fastify = Fastify()
 
   await fastify.register(fastifyOrama, {
@@ -83,5 +83,7 @@ it('Expose a getOrama function', async () => {
     }
   })
 
-  strictEqual(fastify.orama, fastify.getOrama())
+  const withOrama = fastify.withOrama()
+
+  strictEqual(fastify.orama, withOrama.orama)
 })

test/types/index.test-d.ts

@@ -0,0 +1,76 @@
+import { expectType } from 'tsd'
+
+import { InternalTypedDocument, Orama, PartialSchemaDeep, Results, Schema, SearchParams, TypedDocument } from '@orama/orama'
+import Fastify from 'fastify'
+import fp from 'fastify-plugin'
+
+import { PersistenceInFile, PersistenceInMemory, fastifyOrama } from '../..'
+
+const app = Fastify()
+
+const mySchema = {
+  quote: 'string',
+  author: 'string'
+} as const
+type MySchema = Schema<typeof mySchema>
+
+
+app.register(fastifyOrama, {
+  schema: mySchema,
+  prefix: '/api/orama',
+  language: 'en'
+})
+
+app.register(fastifyOrama, {
+  persistence: new PersistenceInMemory()
+})
+
+app.register(fastifyOrama, {
+  persistence: new PersistenceInMemory({
+    jsonIndex: 'index.json'
+  })
+})
+
+app.register(fastifyOrama, {
+  persistence: new PersistenceInFile()
+})
+app.register(fastifyOrama, {
+  persistence: new PersistenceInFile({
+    filePath: 'index.json',
+    format: 'json',
+    mustExistOnStart: true
+  })
+})
+
+const appWithOrama = app.withOrama<typeof mySchema>()
+const id = await appWithOrama.orama.insert({ quote: 'Hello', author: 'World' })
+expectType<string>(id)
+
+appWithOrama.get('/hello', async () => {
+
+  const {orama} = appWithOrama
+  const result = await orama.search({ term: 'hello' })
+
+  expectType<Results<InternalTypedDocument<MySchema>>>(result)
+  expectType<string>(result.hits[0].document.author)
+
+  return {
+    hello: result.hits
+  }
+})
+
+expectType<{
+  insert: (document: PartialSchemaDeep<TypedDocument<Orama<typeof mySchema>>>) => Promise<string>,
+  search: (params: SearchParams<Orama<Schema<typeof mySchema>>, typeof mySchema>) => Promise<Results<Schema<typeof mySchema>>>,
+  persist?: () => Promise<any>,
+}>(appWithOrama.orama)
+
+fp(function(fastify) {
+  const fastifyWithOrama = fastify.withOrama<typeof mySchema>()
+
+  expectType<{
+    insert: (document: PartialSchemaDeep<TypedDocument<Orama<typeof mySchema>>>) => Promise<string>,
+    search: (params: SearchParams<Orama<Schema<typeof mySchema>>, typeof mySchema>) => Promise<Results<Schema<typeof mySchema>>>,
+    persist?: () => Promise<any>,
+  }>(fastifyWithOrama.orama)
+})

test/types/index.ts

@@ -0,0 +1,30 @@
+import Fastify from 'fastify'
+
+import { PersistenceInMemory, fastifyOrama } from '../..'
+
+(async function () {
+  const app = Fastify()
+
+  const mySchema = {
+    quote: 'string',
+    author: 'string'
+  } as const
+
+  await app.register(fastifyOrama, {
+    schema: mySchema,
+    persistence: new PersistenceInMemory()
+  })
+
+  const appWithOrama = app.withOrama<typeof mySchema>()
+  const id = await appWithOrama.orama.insert({ quote: 'Hello', author: 'World' })
+
+  appWithOrama.get('/hello', async () => {
+
+    const {orama} = appWithOrama
+    const result = await orama.search({ term: 'hello' })
+
+    return {
+      hello: result.hits
+    }
+  })
+})();