UNPKG

6.54 kBTypeScriptView Raw
1
2import { Cookie, CookieOptions } from "./cookies.js";
3import { CookieParseOptions, CookieSerializeOptions } from "cookie-es";
4
5//#region lib/server-runtime/sessions.d.ts
6/**
7 * An object of name/value pairs to be used in the session.
8 */
9interface SessionData {
10 [name: string]: any;
11}
12/**
13 * Session persists data across HTTP requests.
14 *
15 * @see https://reactrouter.com/explanation/sessions-and-cookies#sessions
16 */
17interface Session<Data = SessionData, FlashData = Data> {
18 /**
19 * A unique identifier for this session.
20 *
21 * Note: This will be the empty string for newly created sessions and
22 * sessions that are not backed by a database (i.e. cookie-based sessions).
23 */
24 readonly id: string;
25 /**
26 * The raw data contained in this session.
27 *
28 * This is useful mostly for SessionStorage internally to access the raw
29 * session data to persist.
30 */
31 readonly data: FlashSessionData<Data, FlashData>;
32 /**
33 * Returns `true` if the session has a value for the given `name`, `false`
34 * otherwise.
35 */
36 has(name: (keyof Data | keyof FlashData) & string): boolean;
37 /**
38 * Returns the value for the given `name` in this session.
39 */
40 get<Key extends (keyof Data | keyof FlashData) & string>(name: Key): (Key extends keyof Data ? Data[Key] : undefined) | (Key extends keyof FlashData ? FlashData[Key] : undefined) | undefined;
41 /**
42 * Sets a value in the session for the given `name`.
43 */
44 set<Key extends keyof Data & string>(name: Key, value: Data[Key]): void;
45 /**
46 * Sets a value in the session that is only valid until the next `get()`.
47 * This can be useful for temporary values, like error messages.
48 */
49 flash<Key extends keyof FlashData & string>(name: Key, value: FlashData[Key]): void;
50 /**
51 * Removes a value from the session.
52 */
53 unset(name: keyof Data & string): void;
54}
55type FlashSessionData<Data, FlashData> = Partial<Data & { [Key in keyof FlashData as FlashDataKey<Key & string>]: FlashData[Key] }>;
56type FlashDataKey<Key extends string> = `__flash_${Key}__`;
57type CreateSessionFunction = <Data = SessionData, FlashData = Data>(initialData?: Data, id?: string) => Session<Data, FlashData>;
58/**
59 * Creates a new Session object.
60 *
61 * Note: This function is typically not invoked directly by application code.
62 * Instead, use a `SessionStorage` object's `getSession` method.
63 *
64 * @category Utils
65 * @param initialData The initial data for the session.
66 * @param id The identifier for the session. Defaults to an empty string for a
67 * new session.
68 * @returns A new {@link Session} object.
69 */
70declare const createSession: CreateSessionFunction;
71/**
72 * A function that determines whether a value is a React Router {@link Session}
73 * object.
74 *
75 * @public
76 * @category Utils
77 * @mode framework
78 * @mode data
79 * @param object The value to check.
80 * @returns `true` if the value is a React Router {@link Session} object;
81 * otherwise, `false`.
82 */
83type IsSessionFunction = (object: any) => object is Session;
84/**
85 * Returns `true` if a value is a React Router {@link Session} object.
86 *
87 * @public
88 * @category Utils
89 * @mode framework
90 * @mode data
91 * @param object The value to check.
92 * @returns `true` if the value is a React Router {@link Session} object;
93 * otherwise, `false`.
94 */
95declare const isSession: IsSessionFunction;
96/**
97 * SessionStorage stores session data between HTTP requests and knows how to
98 * parse and create cookies.
99 *
100 * A SessionStorage creates Session objects using a `Cookie` header as input.
101 * Then, later it generates the `Set-Cookie` header to be used in the response.
102 */
103interface SessionStorage<Data = SessionData, FlashData = Data> {
104 /**
105 * Parses a Cookie header from a HTTP request and returns the associated
106 * Session. If there is no session associated with the cookie, this will
107 * return a new Session with no data.
108 */
109 getSession: (cookieHeader?: string | null, options?: CookieParseOptions) => Promise<Session<Data, FlashData>>;
110 /**
111 * Stores all data in the Session and returns the Set-Cookie header to be
112 * used in the HTTP response.
113 */
114 commitSession: (session: Session<Data, FlashData>, options?: CookieSerializeOptions) => Promise<string>;
115 /**
116 * Deletes all data associated with the Session and returns the Set-Cookie
117 * header to be used in the HTTP response.
118 */
119 destroySession: (session: Session<Data, FlashData>, options?: CookieSerializeOptions) => Promise<string>;
120}
121/**
122 * SessionIdStorageStrategy is designed to allow anyone to easily build their
123 * own SessionStorage using `createSessionStorage(strategy)`.
124 *
125 * This strategy describes a common scenario where the session id is stored in
126 * a cookie but the actual session data is stored elsewhere, usually in a
127 * database or on disk. A set of create, read, update, and delete operations
128 * are provided for managing the session data.
129 */
130interface SessionIdStorageStrategy<Data = SessionData, FlashData = Data> {
131 /**
132 * The Cookie used to store the session id, or options used to automatically
133 * create one.
134 */
135 cookie?: Cookie | (CookieOptions & {
136 name?: string;
137 });
138 /**
139 * Creates a new record with the given data and returns the session id.
140 */
141 createData: (data: FlashSessionData<Data, FlashData>, expires?: Date) => Promise<string>;
142 /**
143 * Returns data for a given session id, or `null` if there isn't any.
144 */
145 readData: (id: string) => Promise<FlashSessionData<Data, FlashData> | null>;
146 /**
147 * Updates data for the given session id.
148 */
149 updateData: (id: string, data: FlashSessionData<Data, FlashData>, expires?: Date) => Promise<void>;
150 /**
151 * Deletes data for a given session id from the data store.
152 */
153 deleteData: (id: string) => Promise<void>;
154}
155/**
156 * Creates a SessionStorage object using a SessionIdStorageStrategy.
157 *
158 * Note: This is a low-level API that should only be used if none of the
159 * existing session storage options meet your requirements.
160 *
161 * @category Utils
162 * @param strategy The strategy used to store session identifiers and data.
163 * @returns A {@link SessionStorage} object that persists session data using the
164 * provided strategy.
165 */
166declare function createSessionStorage<Data = SessionData, FlashData = Data>({
167 cookie: cookieArg,
168 createData,
169 readData,
170 updateData,
171 deleteData
172}: SessionIdStorageStrategy<Data, FlashData>): SessionStorage<Data, FlashData>;
173//#endregion
174export { FlashSessionData, IsSessionFunction, Session, SessionData, SessionIdStorageStrategy, SessionStorage, createSession, createSessionStorage, isSession };
\No newline at end of file