@ethicdevs/fastify-custom-session

fastify-custom-session

A Fastify (v3.x+) plugin that let you use session and decide only where to load/save from/to

Built-in adapters

• FirebaseSessionAdapter (firebase-admin) [fully working]
• PrismaSessionAdapter (@prisma/client compat layer) [fully working]
• PostgresSessionAdapter (pg, pg-pool) [wip]

Installation

$ yarn add @ethicdevs/fastify-custom-session
# or
$ npm i @ethicdevs/fastify-custom-session

Usage

import fastifyCustomSession, {
  // Adapters for popular softwares/services
  FirebaseSessionAdapter, // Pick one ;)
  PostgresSessionAdapter, // Pick one ;)
  PrismaSessionAdapter, // Pick one ;)
} from "@ethicdevs/fastify-custom-session";

let server = null;

function main() {
  server = fastify(); // provide your own
  // ...
  server.register(fastifyCustomSession, {
    password: "super-secret-session-secret", // or better: Env.SESSION_SECRET,
    cookieName: "my_app_session_id", // or better: Env.COOKIE_NAME,
    cookieOptions: {
      domain: `.my-app.com`, // or better: `.${Env.DEPLOYMENT_DOMAIN}`,
      httpOnly: true,
      expires: new Date(Date.now() + 10 * (8 * 3600) * 1000), // 10 days in secs
      path: "/",
      secure: false,
      sameSite: "lax",
      signed: true,
    },
    initialSession: { // initial data in session (so you can avoid null's)
      whateverYouWant: '<unset>',
      aNullableProp: null,
      mySuperObject: {
        foo: '<unset>',
        bar: 0,
        baz: '<unset>',
      };
    },
    storeAdapter: new PickedSessionAdapter({
      /* ... AdapterOptions ... */
    }) as any,
  });
}

main();

then if you are a TypeScript user you will need to defined the shape of the session.data object, you can do so easily by adding the following lines to your types/global/index.d.ts file:

// use declaration merging to provide custom session interface
declare module "@ethicdevs/fastify-custom-session" {
  declare interface CustomSession {
    // request.session.data shape
    whateverYouWant: string;
    aNullableProp: null | string;
    mySuperObject: {
      foo: string;
      bar: number;
      baz: string;
    };
  }
}

later on during request before you send the headers/response, typically in your controller/handler:

const myRequestHandler = async (request, reply) => {
  request.session.data.whateverYouWant = "foo";
  request.session.data.aNullableProp = "not null anymore";
  request.session.data.mySuperObject = {
    foo: "bar",
    bar: 42,
    baz: "quxx",
  };

  return reply.send("Hello with session!");
};

const mySecondRequestHandler = async (request, reply) => {
  // if you're a typescript user, enjoy ;)
  /* request.session.data.
                    | [p] whateverYouWant
                    | [p] mySuperObject */

  request.session.data.whateverYouWant; // "foo"
  request.session.data.aNullableProp; // "not null anymore"
  request.session.data.object.foo; // "bar"
  request.session.data.object.bar; // 42

  return reply.send(
    "Cool value from session:" + request.session.data.object.baz,
  );
  // "Cool value from session: quxx"
};

then enjoy the session being available both in your controllers/handlers and in your data store table/collection (linked to the Adapter you chosen in first step).

License

The MIT license.