feat: session support

[pi0]

Resolves #58

This PR adds basic session support. Sessions are sealed (encrypted and signed with a private key) in cookies using iron-webcrypto (thanks @brc-dd ❤️) and uncrypto to work out of with Node.js and other environments.

The encrypted session is carried over cookies, therefore no server storage is required for session support.

Multiple session support is also possible with this implementation and custom name option (default is h3 and used for cookie name as well )

Default cookie options are secure, httpOnly with path of / (can be configured)

Exposed utils:

• useSession: Initializes session and returns an { data, id, update(val), clear() } interface to manage session. Wrapping getSession, updateSession and clearSession
• getSession: Treis to reuse or otherwise init an empty session for user
• updateSession: Updates session both in cookie and context. Also initializes if not initialized yet
• clearSession: Clears session from both cookie and context

Simple usage:

import { useSession } from 'h3'

const sessionPassword = "secretsecretsecretsecretsecretsecretsecret"

export default eventHandler(async (event) => {
      const session = await useSession<{ ctr: number }>(event, { password: sessionPassword });
      await session.update((data) => ({ ctr: Number(data.ctr || 0) + 2 }));
      await session.update({ ctr: Number(session.data.ctr || 0) - 1 });
      return `Hello! You visited this page ${session.data.ctr} times. session id: ${session.id})`;
})

Known issues:

• each updates appends a new cookie. fixing in second PR (~> fix(setCookie): override existing set-cookie header with same name #316)

[codecov]

Codecov Report

Merging #315 (d8ae76d) into main (9db177f) will decrease coverage by 3.62%.
The diff coverage is 31.03%.

@@            Coverage Diff             @@
##             main     #315      +/-   ##
==========================================
- Coverage   77.27%   73.66%   -3.62%     
==========================================
  Files          21       22       +1     
  Lines        1725     1868     +143     
  Branches      287      287              
==========================================
+ Hits         1333     1376      +43     
- Misses        392      492     +100     

Impacted Files	Coverage Δ
src/utils/session.ts	27.00% <27.00%> (ø)
src/types.ts	100.00% <100.00%> (ø)
src/utils/index.ts	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[BananaAcid]

Seems to me, there is an export missing for one of the types SessionUpdate - which makes referencing the type in a wrapper fn harder. Is that actually on purpose?

• currently trying to document the usage for me and my coworkers

[peerreynders]

@BananaAcid

Is that actually on purpose?

My impression is that the TS community likes to keep their types implicit in order to minimize the potential maintenance overhead of explicit (and published) types. If you want to explicitly capture/name the type:

import { updateSession } from "h3";

type Holder = {
  count: number;
};

type HolderUpdate = (Parameters<typeof updateSession<Holder>>)[2];

TypeScript Handbook: Parameters<type>