feat: add defineConfig and change factory method name

Author: macropygia

.changeset/chilly-swans-begin.md

@@ -0,0 +1,5 @@
+---
+"elysia-openid-client": patch
+---
+
+Add defineConfig

.changeset/large-maps-fold.md

@@ -0,0 +1,5 @@
+---
+"elysia-openid-client": patch
+---
+
+Change factory method name from create to factory

.gitignore

@@ -1,7 +1,6 @@
 .env
 .temp
-docs
 *.js
-*.d.ts
+index.d.ts
 .vscode/settings.json
 node_modules

__mock__/const.ts

@@ -146,7 +146,7 @@ export const mockStatus = {
 
 export const mockBaseClient = {
   ...mockBaseOptions,
-  create: mock(),
+  factory: mock(),
   initialize: mock(),
   validateOptions: mock(),
   createSession: mock(),

__scripts__/rebuildMockDatabases.ts

@@ -26,7 +26,7 @@ if (fs.existsSync(lowMockFile)) {
   fs.unlinkSync(lowMockFile);
 }
 
-const lowdb = await LowdbAdapter.create({
+const lowdb = await LowdbAdapter.factory({
   filename: lowMockFile,
 });
 await lowdb.insert(mockActiveSession);
@@ -38,7 +38,7 @@ if (fs.existsSync(lokiMockFile)) {
   fs.unlinkSync(lokiMockFile);
 }
 
-const loki = await LokiFileAdapter.create({
+const loki = await LokiFileAdapter.factory({
   filename: lokiMockFile,
   autosaveInterval: 500,
 });

__test__/general.test.ts

@@ -17,7 +17,7 @@ describe("Integration/general", async () => {
 
   const client_id = "mock-client-id";
   const client_secret = "mock-client-secret";
-  const oidcClient = await OidcClient.create({
+  const oidcClient = await OidcClient.factory({
     baseUrl,
     issuerUrl,
     clientMetadata: {

package.json

@@ -22,6 +22,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./config": "./src/config/index.ts",
     "./*": "./src/*.ts",
     "./package.json": "./package.json"
   },

src/config/index.ts

@@ -0,0 +1,5 @@
+import type { OIDCClientOptions } from "../types.js";
+
+export const defineConfig = (
+  config?: OIDCClientOptions,
+): OIDCClientOptions | undefined => config;

src/core/BaseOidcClient.ts

@@ -34,11 +34,11 @@ export class BaseOidcClient {
   settings: OIDCClientSettings;
   /** Cookie settings */
   cookieSettings: OIDCClientCookieSettings;
-  /** OIDC Issuer (Initialize at create()) */
+  /** OIDC Issuer (Initialize at factory()) */
   issuer!: Issuer<BaseClient>;
-  /** OIDC Issuer metadata (Initialize at create()) */
+  /** OIDC Issuer metadata (Initialize at factory()) */
   issuerMetadata!: IssuerMetadata;
-  /** OIDC Client (Initialize at create()) */
+  /** OIDC Client (Initialize at factory()) */
   client!: BaseClient;
   /** Plugin database */
   sessions: OIDCClientDataAdapter;
@@ -93,7 +93,7 @@ export class BaseOidcClient {
    * @param options
    * @returns BaseOidcClient instance
    */
-  static async create(options: OIDCClientOptions) {
+  static async factory(options: OIDCClientOptions) {
     const instance = new BaseOidcClient(options);
     await instance.initialize();
     return instance;

src/core/OidcClient.ts

@@ -16,7 +16,7 @@ import { BaseOidcClient } from "./BaseOidcClient";
 /**
  * OpenID Connect client plugin for ElysiaJS
  * - Usage:
- *   - `const client = await BaseOidcClient.create(options);`
+ *   - `const client = await BaseOidcClient.factory(options);`
  *   - `const endpoints = client.getEndpoints();`
  *   - `const hook = client.getAuthHook();`
  */
@@ -27,7 +27,7 @@ export class OidcClient extends BaseOidcClient {
    * @static
    * @returns OidcClient instance
    */
-  static async create(options: OIDCClientOptions) {
+  static async factory(options: OIDCClientOptions) {
     const instance = new OidcClient(options);
     await instance.initialize();
     return instance;

src/core/baseOidcClient.test.ts

@@ -14,7 +14,7 @@ describe("Unit/core/BaseOidcClient", () => {
       });
 
       const mockOptions = structuredClone(mockBaseOptions);
-      const client = await BaseOidcClient.create({
+      const client = await BaseOidcClient.factory({
         ...mockOptions,
         issuerUrl: `http://localhost:${opPort}`,
         settings: defaultSettings,

src/dataAdapters/LokiFileAdapter.ts

@@ -29,7 +29,7 @@ const defaultOptions: LokiFileAdapterOptions = {
 
 /**
  * File-system data adapter using LokiJS
- * - Usage: `const dataAdapter = await LokiFileAdapter.create();`
+ * - Usage: `const dataAdapter = await LokiFileAdapter.factory();`
  * - Requires: `bun add lokijs` and `bun add -D @types/lokijs`
  * @see [LokiJS](https://techfort.github.io/LokiJS/)
  */
@@ -71,7 +71,7 @@ export class LokiFileAdapter extends BaseLokiAdapter {
    * @param options LokiFileAdapterOptions
    * @returns LokiFileAdapter instance
    */
-  static async create(options?: Partial<LokiFileAdapterOptions>) {
+  static async factory(options?: Partial<LokiFileAdapterOptions>) {
     const instance = new LokiFileAdapter(options);
     await instance.initialize();
     return instance;

src/dataAdapters/LowdbAdapter.ts

@@ -39,7 +39,7 @@ export class LowdbAdapter implements OIDCClientDataAdapter {
    * @param options LokiFileAdapterOptions
    * @returns LokiFileAdapter instance
    */
-  static create = async (options?: Partial<LowdbAdapterOptions>) => {
+  static factory = async (options?: Partial<LowdbAdapterOptions>) => {
     const instance = new LowdbAdapter(options);
     await instance.initialize();
     return instance;

src/dataAdapters/lokiFileAdapter.test.ts

@@ -6,7 +6,7 @@ import { LokiFileAdapter } from "./LokiFileAdapter";
 
 describe("Unit/dataAdapter/LokiFileAdapter", () => {
   test("Default", async () => {
-    const db = await LokiFileAdapter.create({
+    const db = await LokiFileAdapter.factory({
       filename: lokiTempFile,
       autosaveInterval: 1000,
     });
@@ -60,7 +60,7 @@ describe("Unit/dataAdapter/LokiFileAdapter", () => {
   });
 
   test("Load existing database", async () => {
-    const db = await LokiFileAdapter.create({
+    const db = await LokiFileAdapter.factory({
       filename: lokiMockFile,
     });
     expect(db.fetch(mockActiveSession.sessionId)).toMatchObject(

src/dataAdapters/lowdbAdapter.test.ts

@@ -5,7 +5,7 @@ import { LowdbAdapter } from "./LowdbAdapter";
 
 describe("Unit/dataAdapter/LowdbAdapter", () => {
   test("Default", async () => {
-    const db = await LowdbAdapter.create();
+    const db = await LowdbAdapter.factory();
 
     // Insert & fetch
     await db.insert({
@@ -45,7 +45,7 @@ describe("Unit/dataAdapter/LowdbAdapter", () => {
   // NOTES: Does not work only in test (due to Bun?)
   // biome-ignore lint/suspicious/noSkippedTests: <explanation>
   test.skip("Load existing database", async () => {
-    const db = await LowdbAdapter.create({
+    const db = await LowdbAdapter.factory({
       filename: lowMockFile,
     });
     expect(db.fetch(mockActiveSession.sessionId)).toMatchObject(

src/methods/getEndpoints.test.ts

@@ -17,7 +17,7 @@ describe("Unit/methods/getEndpoints", async () => {
     .listen(opPort);
 
   const mockOptions = structuredClone(mockBaseOptions);
-  const rp = await OidcClient.create({
+  const rp = await OidcClient.factory({
     ...mockOptions,
     baseUrl: `http://localhost:${rpPort}`,
     issuerUrl: `http://localhost:${opPort}`,

src/methods/initialize.test.ts

@@ -12,7 +12,7 @@ describe("Unit/methods/initialize", async () => {
 
   test("Default", async () => {
     const mockOptions = structuredClone(mockBaseOptions);
-    const mockClinet = await BaseOidcClient.create({
+    const mockClinet = await BaseOidcClient.factory({
       ...mockOptions,
       issuerUrl: `http://localhost:${opPort}`,
     });

src/types.ts

@@ -105,7 +105,7 @@ export interface OIDCClientOptions {
    * @example
    * ```
    * import pino from "pino";
-   * const rp = new OidcClient.create({ ..., logger: pino() });
+   * const rp = new OidcClient.factory({ ..., logger: pino() });
    * ```
    */
   logger?: OIDCClientLogger | null;

website/src/content/docs/examples/multiple-issuer.md

@@ -0,0 +1,80 @@
+---
+title: Multiple Issuer
+---
+
+```typescript
+import Elysia from "elysia";
+import { OidcClient } from "../src";
+import { SQLiteAdapter } from "../src/dataAdapters/SQLiteAdapter";
+// import { OidcClient } from "elysia-openid-client";
+// import { SQLiteAdapter } from "elysia-openid-client/dataAdapters/SQLiteAdapter";
+
+const baseUrl = "https://app.example.com";
+
+// Use the same data adapter for all issuers
+const dataAdapter = new SQLiteAdapter();
+
+// Callback URL: `https://app.example.com/auth/callback`
+const rp1 = await OidcClient.create({
+  baseUrl,
+  issuerUrl: "https://issuer.exmaple.com",
+  clientMetadata: {
+    client_id: "client-id",
+    client_secret: "client-secret",
+  },
+  dataAdapter,
+});
+const endpoints1 = rp1.getEndpoints();
+
+console.log(rp1.issuerMetadata);
+
+// Callback URL: `https://app.example.com/another/callback`
+const rp2 = await OidcClient.create({
+  baseUrl,
+  issuerUrl: "https://another-issuer.exmaple.com",
+  clientMetadata: {
+    client_id: "another-client-id",
+    client_secret: "another-client-secret",
+  },
+  dataAdapter,
+  settings: {
+    pathPrefix: "/another",
+  },
+});
+const endpoints2 = rp2.getEndpoints();
+
+console.log(rp2.issuerMetadata);
+
+// No matter which RP hook is used
+const hook = rp1.getAuthHook({
+  loginRedirectUrl: "/select",
+});
+
+new Elysia()
+  .use(endpoints1)
+  .use(endpoints2)
+  .guard((app) =>
+    app
+      .use(hook)
+      .get("/", ({ sessionStatus }) =>
+        sessionStatus ? "Logged in" : "Restricted",
+      )
+      .get("/status", ({ sessionStatus }) => sessionStatus)
+      // Issuer can be identified from `sessionClaims.iss`
+      .get("/claims", ({ sessionClaims }) => sessionClaims),
+  )
+  .get("/select", ({ set }) => {
+    set.headers["Content-Type"] = "text/html";
+    return `
+<html>
+<body>
+<p><a href="/auth/login">Issuer</a></p>
+<p><a href="/another/login">Another</a></p>
+</body>
+</html>
+    `;
+  })
+  .get("/free", () => "Not restricted")
+  .get("/logout", () => "Logout completed")
+  .listen(80);
+```

website/src/content/docs/examples/single-issuer.md

@@ -0,0 +1,38 @@
+---
+title: Single Issuer
+---
+
+```typescript
+import Elysia from "elysia";
+import { OidcClient } from "../src";
+// import { OidcClient } from "elysia-openid-client";
+
+// Callback URL: `https://app.example.com/auth/callback`
+const rp = await OidcClient.create({
+  baseUrl: "https://app.example.com",
+  issuerUrl: "https://issuer.exmaple.com",
+  clientMetadata: {
+    client_id: "client-id",
+    client_secret: "client-secret",
+  },
+});
+const endpoints = rp.getEndpoints();
+const hook = rp.getAuthHook();
+
+console.log(rp.issuerMetadata);
+
+new Elysia()
+  .use(endpoints)
+  .guard((app) =>
+    app
+      .use(hook)
+      .get("/", ({ sessionStatus }) =>
+        sessionStatus ? "Logged in" : "Restricted",
+      )
+      .get("/status", ({ sessionStatus }) => sessionStatus)
+      .get("/claims", ({ sessionClaims }) => sessionClaims),
+  )
+  .get("/free", () => "Not restricted")
+  .get("/logout", () => "Logout completed")
+  .listen(80);
+```

website/src/content/docs/getting-started.md

@@ -0,0 +1,42 @@
+---
+title: Getting Started
+# description:
+---
+
+```bash
+bun add elysia-openid-client
+```
+
+```typescript
+import Elysia from "elysia";
+import { OidcClient } from "elysia-openid-client";
+
+const rp = await OidcClient.create({
+  baseUrl: "https://app.example.com", // RP URL
+  issuerUrl: "https://issuer.example.com", // OP URL
+  clientMetadata: {
+    client_id: "client-id",
+    client_secret: "client-secret",
+  },
+});
+const endpoints = rp.getEndpoints(); // Endpoints plugin
+const hook = rp.getAuthHook(); // Auth hook plugin
+
+console.log(rp.issuerMetadata); // Show OP metadata
+
+new Elysia()
+  .use(endpoints) // Add endpoints
+  .guard((app) => // Define restricted area
+    app
+      .use(hook) // Add onBeforeHandle hook for authentication/authorization
+      .onBeforeHandle(({ sessionStatus, sessionClaims }) => {
+        // Authorization by name, mail, group, etc.
+      })
+      .get("/", ({ sessionStatus }) => sessionStatus ? "Logged in" : "Restricted")
+      .get("/status", ({ sessionStatus }) => sessionStatus)
+      .get("/claims", ({ sessionClaims }) => sessionClaims),
+  )
+  .get("/free", () => "Not restricted")
+  .get("/logout", () => "Logout completed")
+  .listen(80);
+```