@kravc/dos 1.12.6 → 2.0.0-alpha.1

package/src/Context/__tests__/Context.test.ts

@@ -0,0 +1,271 @@
+import { get } from 'lodash';
+import { randomUUID } from 'crypto';
+import { createContext } from './__helpers';
+import type { LambdaRequest, HttpRequest } from '../Request';
+
+describe('Context', () => {
+  describe('Context.constructor(config, request, extraContext)', () => {
+    const operationId = 'TestOperationId';
+
+    it('should create instance for lambda request', () => {
+      const context = createContext();
+
+      expect(context.query).toEqual({});
+      expect(context.logger).toBe(console);
+      expect(context.headers).toEqual({});
+      expect(context.httpPath).toEqual(`/${operationId}`);
+      expect(context.bodyJson).toBeNull();
+      expect(context.mutation).toBeNull();
+      expect(context.identity).toEqual({});
+      expect(context.requestId).toBeDefined();
+      expect(context.validator).toBeDefined();
+      expect(context.httpMethod).toEqual('get');
+      expect(context.operationId).toBe(operationId);
+      expect(context.requestReceivedAt).toBeDefined();
+
+      expect(() => get(context, 'undefinedAttribute'))
+        .toThrow('"undefinedAttribute" property or method is undefined for Context instance');
+
+      expect(get(context, 'then')).toBeUndefined();
+    });
+
+    it('should create instance for lambda request with body JSON', () => {
+      const request = {
+        body: JSON.stringify({ status: 'ok' }),
+        headers: {},
+        operationId,
+      } as LambdaRequest;
+
+      const context = createContext({ request });
+
+      expect(context.query).toEqual({});
+      expect(context.bodyJson).toEqual(JSON.stringify({ status: 'ok' }));
+      expect(context.mutation).toEqual({ status: 'ok' });
+    });
+
+    it('should create instance for lambda request with body object and query string parameters', () => {
+      const request = {
+        body: { status: 'ok' },
+        headers: {},
+        operationId,
+        queryStringParameters: { id: 'ID' },
+      } as LambdaRequest;
+
+      const context = createContext({ request });
+
+      expect(context.query).toEqual({ id: 'ID' });
+      expect(context.bodyJson).toEqual(JSON.stringify({ status: 'ok' }));
+      expect(context.mutation).toEqual({ status: 'ok' });
+    });
+
+    it('should create instance for HTTP request', () => {
+      const uuid = randomUUID();
+      const items = ['a', 'b', 'c'];
+      const itemsJson = JSON.stringify(items);
+
+      const request = {
+        url: `http://localhost/api/${operationId}?id=ID&items=${itemsJson}`,
+        path: `/api/${operationId}`,
+        method: 'get',
+        headers: { Accept: 'application/json' },
+        requestContext: {
+          requestId: uuid,
+        },
+      } as HttpRequest;
+
+      const context = createContext({ request });
+
+      expect(context.query).toEqual({ id: 'ID', items });
+      expect(context.logger).toBe(console);
+      expect(context.headers).toEqual({ accept: 'application/json' });
+      expect(context.httpPath).toEqual(`/${operationId}`);
+      expect(context.bodyJson).toBeNull();
+      expect(context.mutation).toBeNull();
+      expect(context.identity).toEqual({});
+      expect(context.requestId).toEqual(uuid);
+      expect(context.validator).toBeDefined();
+      expect(context.httpMethod).toEqual('get');
+      expect(context.operationId).toBe(operationId);
+      expect(context.requestReceivedAt).toBeDefined();
+    });
+
+    it('should create instance for HTTP request with httpMethod and without path', () => {
+      const uuid = randomUUID();
+
+      const request = {
+        url: `http://localhost/api/${operationId}?id=ID`,
+        headers: { Accept: 'application/json' },
+        httpMethod: 'get',
+        requestContext: {
+          requestId: uuid,
+        },
+      } as HttpRequest;
+
+      const context = createContext({ request });
+
+      expect(context.httpPath).toEqual(`/${operationId}`);
+      expect(context.httpMethod).toEqual('get');
+      expect(context.operationId).toBe(operationId);
+    });
+
+    it('should create instance for local HTTP request', () => {
+      const uuid = randomUUID();
+
+      const request = {
+        url: `/${operationId}?id=ID`,
+        headers: { Accept: 'application/json' },
+        httpMethod: 'get',
+        requestContext: {
+          requestId: uuid,
+        },
+      } as HttpRequest;
+
+      const context = createContext({ request });
+
+      expect(context.httpPath).toEqual(`/${operationId}`);
+      expect(context.httpMethod).toEqual('get');
+      expect(context.operationId).toBe(operationId);
+    });
+  });
+
+  describe('.set(name, value)', () => {
+    it('add value to the context runtime', () => {
+      const context = createContext();
+      context.set('example', 'test');
+
+      expect(context.get('example')).toEqual('test');
+    });
+  });
+
+  describe('.get(name)', () => {
+    it('returns value if variable is set', () => {
+      const context = createContext();
+      context.set('example', 'test');
+
+      expect(context.get('example')).toEqual('test');
+    });
+
+    it('returns null value if variable is not set', () => {
+      const context = createContext();
+
+      expect(context.get('example')).toBeNull();
+    });
+  });
+
+  describe('.got(name)', () => {
+    it('returns value if variable is set', () => {
+      const context = createContext();
+      context.set('example', 'test');
+
+      expect(context.got('example')).toEqual('test');
+    });
+
+    it('throws exception if variable is not set', () => {
+      const context = createContext();
+
+      expect(() => context.got('example'))
+        .toThrow('Context runtime is missing "example" value, runtime: {}');
+    });
+  });
+
+  describe('.runtimeReset(name)', () => {
+    it('resets context runtime', () => {
+      const context = createContext();
+      context.set('example', 'test');
+
+      expect(context.get('example')).toEqual('test');
+
+      context.runtimeReset();
+
+      expect(context.get('example')).toBeNull();
+    });
+  });
+
+  describe('.identityId', () => {
+    it('returns users ID from context identity', () => {
+      const identity = { sub: 'TEST_USER_ID' };
+      const context = createContext({ identity });
+
+      expect(context.identityId).toEqual('TEST_USER_ID');
+    });
+
+    it('returns SYSTEM if context has no identity', () => {
+      const context = createContext();
+
+      expect(context.identityId).toEqual('SYSTEM');
+    });
+
+    it('returns SYSTEM if context identity has no subject claim', () => {
+      const identity = {};
+      const context = createContext({ identity });
+
+      expect(context.identityId).toEqual('SYSTEM');
+    });
+  });
+
+  describe('.identityName', () => {
+    it('returns users name from context identity name claim', () => {
+      const identity = { name: 'John Doe' };
+      const context = createContext({ identity });
+
+      expect(context.identityName).toEqual('John Doe');
+    });
+
+    it('returns users name from context identity first and last name claims', () => {
+      const identity = { firstName: 'John', lastName: 'Doe' };
+      const context = createContext({ identity });
+
+      expect(context.identityName).toEqual('John Doe');
+    });
+
+    it('returns null if context has no identity', () => {
+      const context = createContext();
+
+      expect(context.identityName).toBeNull();
+    });
+
+    it('returns null if context identity has no name related claims', () => {
+      const identity = {};
+      const context = createContext({ identity });
+
+      expect(context.identityName).toBeNull();
+    });
+  });
+
+  describe('.toJSON()', () => {
+    it('returns JSON serializable object', () => {
+      const identity = { name: 'John Doe' };
+      const context = createContext({ identity });
+
+      expect(context.toJSON()).toEqual({
+        bodyJson: null,
+        headers: {},
+        httpMethod: 'get',
+        httpPath: '/TestOperationId',
+        identity: {
+          name: 'John Doe',
+        },
+        mutation: null,
+        operationId: 'TestOperationId',
+        query: {},
+        requestId: context.requestId,
+        requestReceivedAt: context.requestReceivedAt,
+        runtime: {},
+      });
+    });
+  });
+
+  describe('.[inspect.custom]()', () => {
+    it('returns object serializable for logging', () => {
+      const context = createContext();
+      console.log(context);
+    });
+  });
+
+  describe('.isLive', () => {
+    it('flags if running in non test environment', () => {
+      const context = createContext();
+      expect(context.isLive).toEqual(true);
+    });
+  });
+});

package/src/Context/__tests__/__helpers.ts

@@ -0,0 +1,86 @@
+import { OpenAPIV2 } from 'openapi-types';
+import { Schema, Validator } from '@kravc/schema';
+import { Context, type Identity } from '../../';
+import type { Request, LambdaRequest, ExtraContext } from '../Request';
+
+const operationId = 'TestOperationId';
+
+const DEFAULT_LAMBDA_REQUEST = {
+  headers: {},
+  operationId,
+} as LambdaRequest;
+
+export const profileSchema = new Schema({
+  id: {},
+  name: { required: true },
+}, 'Profile');
+
+type Props = {
+  request?: Request;
+  schemas?: Schema[];
+  identity?: Identity;
+  extraContext?: ExtraContext;
+};
+
+/** Creates an instace of an operation context. */
+export const createContext = (props: Props = {}): Context => {
+  const {
+    request = DEFAULT_LAMBDA_REQUEST,
+    schemas = [ profileSchema ],
+    identity = {},
+    extraContext = {},
+  } = props;
+
+  const validator = new Validator(schemas);
+
+  const spec = {
+    basePath: '/api',
+    paths: {
+      [`/${operationId}`]: {
+        get: {
+          operationId,
+        },
+      },
+      ['/CreateProfile']: {
+        post: {
+          operationId: 'CreateProfile',
+        },
+      },
+      ['/UpdateProfile']: {
+        post: {
+          operationId: 'UpdateProfile',
+        },
+      },
+      ['/DeleteProfile']: {
+        delete: {
+          operationId: 'DeleteProfile',
+        },
+      },
+      ['/ReadProfile']: {
+        get: {
+          operationId: 'ReadProfile',
+        },
+      },
+      ['/IndexProfiles']: {
+        get: {
+          operationId: 'IndexProfiles',
+        },
+      },
+      ['/ListProfiles']: {
+        get: {
+          operationId: 'ListProfiles',
+        },
+      },
+      ['/Health']: {
+        get: {
+          operationId: 'Health',
+        },
+      }
+    }
+  } as unknown as OpenAPIV2.Document;
+
+  const context = new Context({ spec, validator }, request, extraContext);
+  context.identity = identity;
+
+  return context;
+};

package/src/Context/getHttpMethod.ts

@@ -0,0 +1,21 @@
+import { got } from '@kravc/schema';
+import { OpenAPIV2 } from 'openapi-types';
+import type { Request, LambdaRequest, HttpRequest } from './Request';
+
+/** Returns HTTP method of a request. */
+const getHttpMethod = (spec: OpenAPIV2.Document, request: Request): string => {
+  const { operationId } = request as LambdaRequest;
+
+  if (operationId) {
+    const methods = Object.keys(got(spec.paths, `/${operationId}`) as OpenAPIV2.PathsObject);
+    const method = methods[0] as string;
+
+    return method;
+  }
+
+  const { method, httpMethod } = request as HttpRequest;
+
+  return (method || httpMethod!).toLowerCase();
+};
+
+export default getHttpMethod;

package/src/Context/getHttpPath.ts

@@ -0,0 +1,34 @@
+import { get } from 'lodash';
+import { OpenAPIV2 } from 'openapi-types';
+import type { Request, LambdaRequest, HttpRequest } from './Request';
+
+const BASE_URL = 'http://localhost:3000';
+
+/** Returns HTTP path of a request. */
+const getHttpPath = (spec: OpenAPIV2.Document, request: Request): string => {
+  const { basePath } = spec;
+  const { operationId } = request as LambdaRequest;
+
+  if (operationId) {
+    return `/${operationId}`;
+  }
+
+  const httpRequest = request as HttpRequest;
+
+  let { path } = httpRequest;
+
+  if (!path) {
+    const { url } = httpRequest;
+    const _url = new URL(url, BASE_URL);
+
+    path = get(_url, 'pathname', '/');
+  }
+
+  const httpPath = path
+    .replace(basePath!, '/')
+    .replace('//', '/');
+
+  return httpPath;
+};
+
+export default getHttpPath;

package/src/Context/getMutationParameters.ts

@@ -0,0 +1,35 @@
+import { isString } from 'lodash';
+import type { MutationMap, Request } from './Request';
+
+/** Returns mutation parameters of a request. */
+const getMutationParameters = (request: Request) => {
+  const result = {
+    bodyJson: null,
+    mutation: null,
+  } as {
+    bodyJson: string | null;
+    mutation: MutationMap | null;
+  };
+
+  const { body } = request;
+
+  if (!body) {
+    return result;
+  }
+
+  const isJSON = isString(body);
+
+  if (isJSON) {
+    result.bodyJson = body;
+    result.mutation = JSON.parse(body);
+
+    return result;
+  }
+
+  result.bodyJson = JSON.stringify(body);
+  result.mutation = body;
+
+  return result;
+};
+
+export default getMutationParameters;

package/src/Context/getOperationId.ts

@@ -0,0 +1,23 @@
+import { get } from 'lodash';
+import getHttpPath from './getHttpPath';
+import getHttpMethod from './getHttpMethod';
+import { OpenAPIV2 } from 'openapi-types';
+import type { Request, LambdaRequest } from './Request';
+
+const UNDEFINED_VALUE = 'undefined';
+
+/** Returns operation ID for a request. */
+const getOperationId = (spec: OpenAPIV2.Document, request: Request): string => {
+  const { operationId } = request as LambdaRequest;
+
+  if (operationId) {
+    return operationId;
+  }
+
+  const httpPath = getHttpPath(spec, request);
+  const httpMethod = getHttpMethod(spec, request);
+
+  return get(spec.paths, `${httpPath}.${httpMethod}.operationId`, UNDEFINED_VALUE) as string;
+};
+
+export default getOperationId;

package/src/Context/getQueryParameters.ts

@@ -0,0 +1,45 @@
+import { get } from 'lodash';
+import type { QueryMap, Request } from './Request';
+
+const BASE_URL = 'http://localhost:3000';
+
+/** Returns query parameters of a request. */
+const getQueryParameters = (request: Request): QueryMap => {
+  let parameters = {} as QueryMap;
+
+  const url = get(request, 'url');
+
+  if (url) {
+    const { searchParams } = new URL(url, BASE_URL);
+    parameters = Object.fromEntries(searchParams);
+  }
+
+  const queryStringParameters = get(request, 'queryStringParameters');
+
+  if (queryStringParameters) {
+    const keys = Object.keys(queryStringParameters);
+
+    for (const key of keys) {
+      const value = queryStringParameters[key] as string;
+      queryStringParameters[key] = decodeURIComponent(value);
+    }
+
+    parameters = queryStringParameters;
+  }
+
+  const queryKeys = Object.keys(parameters);
+
+
+  for (const queryKey of queryKeys) {
+    const value = parameters[queryKey] as string;
+    const isArrayOfStrings = `${value}`.startsWith('["');
+
+    if (isArrayOfStrings) {
+      parameters[queryKey] = JSON.parse(`${value}`);
+    }
+  }
+
+  return parameters;
+};
+
+export default getQueryParameters;

package/src/Context/index.ts

@@ -0,0 +1,12 @@
+import Context from './Context';
+import withSafeAttributes from './withSafeAttributes';
+
+export default Context;
+
+export {
+  Context,
+  withSafeAttributes,
+};
+
+export type * from './Context';
+export type * from './Request';

package/src/Context/withSafeAttributes.ts

@@ -0,0 +1,39 @@
+import { got } from '@kravc/schema';
+
+/**
+ * Returns instance of an object with safe attributes.
+ *
+ * ## Intent
+ *
+ * Wraps an object instance in a Proxy that enforces safe attribute access. This function ensures that:
+ * - Properties and methods must exist on the instance before they can be accessed
+ * - Clear, descriptive errors are thrown when accessing undefined properties/methods
+ * - The object cannot be accidentally treated as a Promise (by returning `undefined` for `then`)
+ *
+ * This is particularly useful for component classes where you want to catch typos and undefined
+ * property access early with helpful error messages that include the class name.
+ *
+ * ## Use Cases
+ *
+ * 1. **Component Safety**: Wrap component instances to ensure all property/method accesses are valid
+ * 2. **Early Error Detection**: Catch typos and undefined accesses at runtime with clear error messages
+ * 3. **Promise Prevention**: Prevent objects from being accidentally treated as Promises in async contexts
+ * 4. **Type Safety**: Provide runtime validation complementing TypeScript's compile-time checks
+ */
+function withSafeAttributes<T>(targetInstance: T, className: string): T {
+  return new Proxy(targetInstance as object, {
+    /** Ensures attribute is defined as property or method of the instance. */
+    get(target: Record<string, unknown>, prop: string) {
+      const shouldSkip = ['then'].includes(prop);
+
+      if (shouldSkip) {
+        return undefined;
+      }
+
+      const errorTemplate = `"$PATH" property or method is undefined for ${className} instance`;
+      return got(target, prop, errorTemplate);
+    }
+  }) as T;
+};
+
+export default withSafeAttributes;