@rvoh/psychic-spec-helpers 0.7.2 → 0.7.3

package/dist/esm/src/unit/OpenapiSpecSession.js

@@ -6,25 +6,303 @@ export class OpenapiSpecSession {
     constructor(_session) {
         this._session = _session;
     }
-    // final
-    async get(uri, expectedStatus, opts) {
+    async get(
+    /**
+     * The uri on your background you are trying to hit.
+     * This should be a path, like '/users'.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.get('/posts/{id}', 200, { id: '123' })
+     * ```
+     */
+    uri, 
+    /**
+     * The response status you are expecting to receive
+     * when making this request. It will need to match
+     * one of the accepted response statuses for the
+     * provided uri in your openapi types
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.get('/posts/{id}', 200, { id: '123' })
+     * ```
+     */
+    expectedStatus, 
+    /**
+     * An object containing the path fields required to
+     * fill your uri in, as well as any additional GET
+     * arguments, like `query`, for example.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.get(
+     *   '/posts/{postId}/comments/{id}',
+     *   200,
+     *   {
+     *     postId: '123',
+     *     id: '456',
+     *     query: {
+     *       ...query params here
+     *     }
+     *   }
+     * )
+     * ```
+     *
+     * @param opts.query - query params you want to send up. Must match the
+     *                    query params in the openapi document for this uri.
+     *                    (Optional)
+     *
+     * @param opts.headers - headers you would like to send with your request.
+     *                       (Optional)
+     */
+    opts) {
         return (await this.makeRequest('get', fillOpenapiParams(uri, (opts || {})), expectedStatus, opts));
     }
-    // final
-    async post(uri, expectedStatus, opts = {}) {
+    //
+    //
+    //
+    // begin: POST
+    // has Params
+    async post(
+    /**
+     * The uri on your background you are trying to hit.
+     * This should be a path, like '/users'.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.post('/posts/{id}', 200, { id: '123' })
+     * ```
+     */
+    uri, 
+    /**
+     * The response status you are expecting to receive
+     * when making this request. It will need to match
+     * one of the accepted response statuses for the
+     * provided uri in your openapi types
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.post('/posts/{id}', 200, { id: '123' })
+     * ```
+     */
+    expectedStatus, 
+    /**
+     * An object containing the path fields required to
+     * fill your uri in, as well as any additional POST
+     * arguments, like `data`, for example.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.post(
+     *   '/posts/{postId}/comments/{id}',
+     *   200,
+     *   {
+     *     postId: '123',
+     *     commentId: '456',
+     *     data: {
+     *       ...request body here
+     *     },
+     *     headers: {
+     *       ...headers here
+     *     },
+     *   }
+     * )
+     * ```
+     *
+     * @param opts.data - request body data you want to send up. Must match the
+     *                    requestBody shape in the openapi document for this uri.
+     *                    (Optional)
+     *
+     * @param opts.headers - headers you would like to send with your request.
+     *                       (Optional)
+     */
+    opts) {
         return await this.makeRequest('post', uri, expectedStatus, opts);
     }
-    // final
-    async put(uri, expectedStatus, opts = {}) {
+    async put(
+    /**
+     * The uri on your background you are trying to hit.
+     * This should be a path, like '/users'.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.put('/posts/{id}', 200, { id: '123', data: { name: 'new name' }})
+     * ```
+     */
+    uri, 
+    /**
+     * The response status you are expecting to receive
+     * when making this request. It will need to match
+     * one of the accepted response statuses for the
+     * provided uri in your openapi types
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.put('/posts/{id}', 200, { id: '123', data: { name: 'new name' }})
+     * ```
+     */
+    expectedStatus, 
+    /**
+     * An object containing the path fields required to
+     * fill your uri in, as well as any additional PUT
+     * arguments, like `data`, for example.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.put(
+     *   '/posts/{id}/comments/{commentId}',
+     *   200,
+     *   {
+     *     postId: '123',
+     *     id: '456',
+     *
+     *     data: {
+     *       ...request body here
+     *     },
+     *     headers: {
+     *       ...headers here
+     *     },
+     *   }
+     * )
+     * ```
+     *
+     * @param opts.data - request body data you want to send up. Must match the
+     *                    requestBody shape in the openapi document for this uri.
+     *                    (Optional)
+     *
+     * @param opts.headers - headers you would like to send with your request.
+     *                       (Optional)
+     */
+    opts) {
         return await this.makeRequest('put', fillOpenapiParams(uri, opts || {}), expectedStatus, opts);
     }
-    // final
-    async patch(uri, expectedStatus, opts = {}) {
-        return await this.makeRequest('patch', fillOpenapiParams(uri, opts), expectedStatus, opts);
+    async patch(
+    /**
+     * The uri on your background you are trying to hit.
+     * This should be a path, like '/posts'.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.patch('/posts/{id}', 200, { data: { name: 'new name' }})
+     * ```
+     */
+    uri, 
+    /**
+     * The response status you are expecting to receive
+     * when making this request. It will need to match
+     * one of the accepted response statuses for the
+     * provided uri in your openapi types
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.patch('/posts/{id}', 200, { data: { name: 'new name' }})
+     * ```
+     */
+    expectedStatus, 
+    /**
+     * An object containing the path fields required to
+     * fill your uri in, as well as any additional PATCH
+     * arguments, like `data`, for example.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.patch(
+     *   '/posts/{postId}/comments/{id}',
+     *   200,
+     *   {
+     *     postId: '123',
+     *     commentId: '456',
+     *     data: {
+     *       ...request body here
+     *     },
+     *     headers: {
+     *       ...headers here
+     *     },
+     *   }
+     * )
+     * ```
+     *
+     * @param opts.data - request body data you want to send up. Must match the
+     *                    requestBody shape in the openapi document for this uri.
+     *                    (Optional)
+     *
+     * @param opts.headers - headers you would like to send with your request.
+     *                       (Optional)
+     */
+    opts) {
+        return await this.makeRequest('patch', fillOpenapiParams(uri, opts || {}), expectedStatus, opts);
     }
-    // final
-    async delete(uri, expectedStatus, opts = {}) {
-        return await this.makeRequest('delete', fillOpenapiParams(uri, opts), expectedStatus, opts);
+    async delete(
+    /**
+     * The uri on your background you are trying to hit.
+     * This should be a path, like '/users'.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.delete('/posts/{id}', 200, { id: '123' })
+     * ```
+     */
+    uri, 
+    /**
+     * The response status you are expecting to receive
+     * when making this request. It will need to match
+     * one of the accepted response statuses for the
+     * provided uri in your openapi types
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.delete('/posts/{id}', 200, { id: '123' })
+     * ```
+     */
+    expectedStatus, 
+    /**
+     * An object containing the path fields required to
+     * fill your uri in, as well as any additional DELETE
+     * arguments, like `data`, for example.
+     *
+     * ```ts
+     * const request = new OpenapiSpecRequest<openapiPaths>()
+     * const session = await request.session('post', '/sessions/{token}', 200, { token: 'abc' })
+     * const res = await session.delete(
+     *   '/posts/{postId}/comments/{commentId}',
+     *   200,
+     *   {
+     *     postId: '123',
+     *     commentId: '456',
+     *     data: {
+     *       ...request body here
+     *     },
+     *     headers: {
+     *       ...headers here
+     *     },
+     *   }
+     * )
+     * ```
+     *
+     * @param opts.data - request body data you want to send up. Must match the
+     *                    requestBody shape in the openapi document for this uri.
+     *                    (Optional)
+     *
+     * @param opts.headers - headers you would like to send with your request.
+     *                       (Optional)
+     */
+    opts) {
+        return await this.makeRequest('delete', fillOpenapiParams(uri, opts || {}), expectedStatus, opts);
     }
     async makeRequest(method, uri, expectedStatus, opts = {}) {
         if (expectedStatus === 500) {