@pikku/core 0.7.0 → 0.7.2

package/src/services/logger-console.ts

@@ -0,0 +1,97 @@
+import { Logger, LogLevel } from './logger.js'
+
+/**
+ * A logger implementation that logs messages to the console.
+ */
+export class ConsoleLogger implements Logger {
+  /**
+   * The current logging level.
+   */
+  private level: LogLevel = LogLevel.info
+
+  /**
+   * Sets the logging level.
+   * @param level - The logging level to set.
+   */
+  setLevel(level: LogLevel): void {
+    this.level = level
+  }
+
+  /**
+   * Logs a trace message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  trace?(message: string, ...meta: any[]): void {
+    if (this.level <= LogLevel.trace) {
+      console.trace('TRACE:', message, ...meta)
+    }
+  }
+
+  /**
+   * Logs a debug message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  debug(message: string, ...meta: any[]): void {
+    if (this.level <= LogLevel.debug) {
+      console.debug('DEBUG:', message, ...meta)
+    }
+  }
+
+  /**
+   * Logs an informational message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  info(messageOrObj: string | Record<string, any>, ...meta: any[]): void {
+    if (this.level <= LogLevel.info) {
+      console.info('INFO:', messageOrObj, ...meta)
+    }
+  }
+
+  /**
+   * Logs a warning message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void {
+    if (this.level <= LogLevel.warn) {
+      console.warn('WARN:', messageOrObj, ...meta)
+    }
+  }
+
+  /**
+   * Logs an error message.
+   * @param messageOrObj - The message, object, or error to log.
+   * @param meta - Additional metadata to log.
+   */
+  error(
+    messageOrObj: string | Record<string, any> | Error,
+    ...meta: any[]
+  ): void {
+    if (this.level <= LogLevel.error) {
+      console.error(
+        'ERROR:',
+        messageOrObj instanceof Error ? messageOrObj.message : messageOrObj,
+        ...meta
+      )
+      if (messageOrObj instanceof Error) {
+        console.error('STACK:', messageOrObj.stack)
+      }
+    }
+  }
+
+  /**
+   * Logs a message at a specified level.
+   * @param level - The logging level.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  log(level: string, message: string, ...meta: any[]): void {
+    const logLevel = LogLevel[level as keyof typeof LogLevel]
+    if (this.level <= logLevel) {
+      console.log(`${level.toUpperCase()}:`, message, ...meta)
+    }
+  }
+}

package/src/services/logger.ts

@@ -0,0 +1,57 @@
+export enum LogLevel {
+  'trace', // Add this level
+  'debug',
+  'info',
+  'warn',
+  'error',
+  'critical',
+}
+
+/**
+ * Interface for logging messages at various levels.
+ */
+export interface Logger {
+  /**
+   * Logs an informational message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  info(messageOrObj: string | Record<string, any>, ...meta: any[]): void
+
+  /**
+   * Logs a warning message.
+   * @param messageOrObj - The message or object to log.
+   * @param meta - Additional metadata to log.
+   */
+  warn(messageOrObj: string | Record<string, any>, ...meta: any[]): void
+
+  /**
+   * Logs an error message.
+   * @param messageOrObj - The message, object, or error to log.
+   * @param meta - Additional metadata to log.
+   */
+  error(
+    messageOrObj: string | Record<string, any> | Error,
+    ...meta: any[]
+  ): void
+
+  /**
+   * Logs a debug message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  debug(message: string, ...meta: any[]): void
+
+  /**
+   * Logs a trace message.
+   * @param message - The message to log.
+   * @param meta - Additional metadata to log.
+   */
+  trace?(message: string, ...meta: any[]): void
+
+  /**
+   * Sets the logging level.
+   * @param level - The logging level to set.
+   */
+  setLevel(level: LogLevel): void
+}

package/src/services/schema-service.ts

@@ -0,0 +1,26 @@
+/**
+ * Interface for a schema service that handles schema compilation, validation, and management.
+ */
+export interface SchemaService {
+  /**
+   * Compiles a schema with the provided name and value, making it available for use.
+   * @param {string} name - The unique name for the schema.
+   * @param {any} value - The schema definition or configuration to be compiled.
+   * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
+   */
+  compileSchema: (name: string, value: any) => Promise<void> | void
+
+  /**
+   * Validates data against a specified schema.
+   * @param {string} schema - The name of the schema to validate against.
+   * @param {any} data - The data to validate against the schema.
+   * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
+   */
+  validateSchema: (schema: string, data: any) => Promise<void> | void
+
+  /**
+   * Retrieves a set of all registered schema names.
+   * @returns {Set<string>} A set containing the names of all available schemas.
+   */
+  getSchemaNames: () => Set<string>
+}

package/src/services/secret-service.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface for retrieving secrets.
+ */
+export interface SecretService {
+  /**
+   * Retrieves a secret by key.
+   * @param key - The key of the secret to retrieve.
+   * @returns A promise that resolves to the secret value.
+   */
+  getSecretJSON<Return = {}>(key: string): Promise<Return>
+  /**
+   * Retrieves a secret by key.
+   * @param key - The key of the secret to retrieve.
+   * @returns A promise that resolves to the secret value.
+   */
+  getSecret(key: string): Promise<string>
+}

package/src/services/user-session-service.ts

@@ -0,0 +1,53 @@
+import { ChannelStore } from '../channel/channel-store.js'
+import { CoreUserSession } from '../types/core.types.js'
+
+export interface UserSessionService<UserSession extends CoreUserSession> {
+  sessionChanged: boolean
+  setInitial(session: UserSession): void
+  set(session: UserSession): Promise<void> | void
+  clear(): Promise<void> | void
+  get(): Promise<UserSession | undefined> | UserSession | undefined
+}
+
+export class PikkuUserSessionService<UserSession extends CoreUserSession>
+  implements UserSessionService<UserSession>
+{
+  public sessionChanged = false
+  private session: UserSession | undefined
+  constructor(
+    private channelStore?: ChannelStore<unknown, unknown, UserSession>,
+    private channelId?: string
+  ) {
+    if (channelStore && !channelId) {
+      throw new Error('Channel ID is required when using channel store')
+    }
+  }
+
+  public setInitial(session: UserSession) {
+    this.session = session
+  }
+
+  public set(session: UserSession) {
+    this.sessionChanged = true
+    this.session = session
+    return this.channelStore?.setUserSession(this.channelId!, session)
+  }
+
+  public clear() {
+    this.sessionChanged = true
+    this.session = undefined
+    return this.channelStore?.setUserSession(this.channelId!, null)
+  }
+
+  public get(): Promise<UserSession> | UserSession | undefined {
+    if (this.channelStore) {
+      const channel = this.channelStore.getChannelAndSession(this.channelId!)
+      if (channel instanceof Promise) {
+        return channel.then(({ session }) => session)
+      } else {
+        return channel.session
+      }
+    }
+    return this.session
+  }
+}

package/src/services/variables-service.ts

@@ -0,0 +1,6 @@
+export interface VariablesService {
+  get: (name: string) => Promise<string | undefined> | string | undefined
+  getAll: () =>
+    | Promise<Record<string, string | undefined>>
+    | Record<string, string | undefined>
+}

package/src/time-utils.test.ts

@@ -0,0 +1,56 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  getRelativeTimeOffset,
+  getRelativeTimeOffsetFromNow,
+  RelativeTimeInput,
+} from './time-utils'
+
+const approxEqual = (a: number, b: number, delta: number = 10): boolean =>
+  Math.abs(a - b) <= delta
+
+describe('Time Utils', () => {
+  const offsetCases: Array<{ input: RelativeTimeInput; expected: number }> = [
+    { input: { value: 1, unit: 'second' }, expected: 1000 },
+    { input: { value: 2, unit: 'minute' }, expected: 120000 },
+    { input: { value: 1.5, unit: 'hour' }, expected: 5400000 },
+    { input: { value: -1, unit: 'day' }, expected: -86400000 },
+    { input: { value: 1, unit: 'week' }, expected: 604800000 },
+    {
+      input: { value: 2, unit: 'year' },
+      expected: Math.round(2 * 365.25 * 86400 * 1000),
+    },
+  ]
+
+  describe('getRelativeTimeOffset', () => {
+    for (const { input, expected } of offsetCases) {
+      test(`returns ${expected} ms for ${input.value} ${input.unit}`, () => {
+        const actual = getRelativeTimeOffset(input)
+        assert.strictEqual(actual, expected)
+      })
+    }
+  })
+
+  describe('getRelativeTimeOffsetFromNow', () => {
+    test('returns a Date ~1 minute in the future', () => {
+      const now = Date.now()
+      const result = getRelativeTimeOffsetFromNow({ value: 1, unit: 'minute' })
+      const delta = result.getTime() - now
+      assert.ok(
+        approxEqual(delta, 60000),
+        `Expected ~60000ms ahead, got ${delta}ms`
+      )
+    })
+
+    test('returns a Date ~2 hours in the past', () => {
+      const now = Date.now()
+      const result = getRelativeTimeOffsetFromNow({ value: -2, unit: 'hour' })
+      const delta = now - result.getTime()
+      assert.ok(
+        approxEqual(delta, 7200000),
+        `Expected ~7200000ms ago, got ${delta}ms`
+      )
+    })
+  })
+})

package/src/time-utils.ts

@@ -0,0 +1,32 @@
+type TimeUnit = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'year'
+
+export interface RelativeTimeInput {
+  value: number // negative = in the past
+  unit: TimeUnit
+}
+
+const multipliers: Record<TimeUnit, number> = {
+  second: 1,
+  minute: 60,
+  hour: 60 * 60,
+  day: 60 * 60 * 24,
+  week: 60 * 60 * 24 * 7,
+  year: Math.round(365.25 * 60 * 60 * 24),
+}
+
+export const getRelativeTimeOffset = ({
+  value,
+  unit,
+}: RelativeTimeInput): number => {
+  return Math.round(value * multipliers[unit]) * 1000 // convert to milliseconds
+}
+
+/**
+ * Returns a Unix timestamp (in seconds) offset from now by the given duration.
+ * e.g. value = -1 and unit = 'day' => 1 day ago => now - 86400 seconds
+ */
+export const getRelativeTimeOffsetFromNow = (
+  relativeTime: RelativeTimeInput
+): Date => {
+  return new Date(Date.now() + getRelativeTimeOffset(relativeTime))
+}

package/src/types/core.types.ts

@@ -0,0 +1,178 @@
+import type { Logger, LogLevel } from '../services/logger.js'
+import { VariablesService } from '../services/variables-service.js'
+import { EventHubService } from '../channel/eventhub-service.js'
+import { SchemaService } from '../services/schema-service.js'
+import { PikkuHTTP } from '../http/http.types.js'
+import { UserSessionService } from '../services/user-session-service.js'
+import { JWTService } from '../services/jwt-service.js'
+import { SecretService } from '../services/secret-service.js'
+import { PikkuChannel } from '../channel/channel.types.js'
+
+export interface FunctionServicesMeta {
+  optimized: boolean
+  services: string[]
+}
+
+export type FunctionsMeta = Record<
+  string,
+  {
+    pikkuFuncName: string
+    name?: string
+    services: FunctionServicesMeta
+    schemaName: string | null
+    inputs: string[] | null
+    outputs: string[] | null
+  }
+>
+
+export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
+  Required<Pick<T, K>>
+
+/**
+ * Represents a JSON primitive type which can be a string, number, boolean, null, or undefined.
+ */
+export type JSONPrimitive = string | number | boolean | null | undefined
+
+/**
+ * Represents a JSON value which can be a primitive, an array, or an object.
+ */
+export type JSONValue =
+  | JSONPrimitive
+  | JSONValue[]
+  | {
+      [key: string]: JSONValue
+    }
+
+/**
+ * Utility type for making certain keys required and leaving the rest as optional.
+ */
+export type PickRequired<T, K extends keyof T> = Required<Pick<T, K>> &
+  Partial<T>
+
+/**
+ * Utility type for making certain keys optional while keeping the rest required.
+ */
+export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>
+
+/**
+ * Utility type that ensures at least one key in the given type `T` is required.
+ */
+export type RequireAtLeastOne<T> = {
+  [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
+}[keyof T]
+
+/**
+ * Interface for the core configuration settings of Pikku.
+ */
+export type CoreConfig<Config extends Record<string, unknown> = {}> = {
+  /** The log level for the application. */
+  logLevel?: LogLevel
+  /** Secrets used by the application (optional). */
+  secrets?: {}
+} & Config
+
+/**
+ * Represents a core user session, which can be extended for more specific session information.
+ */
+export interface CoreUserSession {}
+
+/**
+ * Interface for core singleton services provided by Pikku.
+ */
+export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
+  /** JWT Service */
+  jwt?: JWTService
+  /** The schema library used to validate data */
+  schema?: SchemaService
+  /** The core configuration for the application. */
+  config: Config
+  /** The logger used by the application. */
+  logger: Logger
+  /** The variable service to be used */
+  variables: VariablesService
+  /** The subscription service that is passed to streams */
+  eventHub?: EventHubService<unknown>
+  /** SecretServce  */
+  secrets?: SecretService
+}
+
+/**
+ * Represents different forms of interaction within Pikku and the outside world.
+ */
+export interface PikkuInteraction {
+  http?: PikkuHTTP
+}
+
+/**
+ * A function that can wrap an interaction and be called before or after
+ */
+export type PikkuMiddleware<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (
+  services: SingletonServices & {
+    userSession: UserSessionService<UserSession>
+  },
+  interactions: PikkuInteraction,
+  next: () => Promise<void>
+) => Promise<void>
+
+/**
+ * Represents the core services used by Pikku, including singleton services and the request/response interaction.
+ */
+export type CoreServices<
+  SingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+  CoreServices extends Record<string, unknown> = {},
+> = SingletonServices &
+  PikkuInteraction & {
+    userSession?: UserSessionService<UserSession>
+    channel?: PikkuChannel<unknown, unknown>
+  } & CoreServices
+
+export type SessionServices<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Services = CoreServices<SingletonServices>,
+> = Omit<Services, keyof SingletonServices | keyof PikkuInteraction | 'session'>
+
+/**
+ * Defines a function type for creating singleton services from the given configuration.
+ */
+export type CreateSingletonServices<
+  Config extends CoreConfig,
+  SingletonServices extends CoreSingletonServices,
+> = (
+  config: Config,
+  existingServices?: Partial<SingletonServices>
+) => Promise<SingletonServices>
+
+/**
+ * Defines a function type for creating session-specific services.
+ */
+export type CreateSessionServices<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  Services extends
+    CoreServices<SingletonServices> = CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (
+  services: SingletonServices,
+  interaction: PikkuInteraction,
+  session: UserSession | undefined
+) => Promise<SessionServices<Services, SingletonServices>>
+
+/**
+ * Defines a function type for creating config.
+ */
+export type CreateConfig<Config extends CoreConfig> = (
+  variables?: VariablesService
+) => Promise<Config>
+
+/**
+ * Represents the documentation for a route, including summary, description, tags, and errors.
+ */
+export type APIDocs = {
+  summary?: string
+  description?: string
+  tags?: string[]
+  errors?: string[]
+}

package/src/utils.ts

@@ -0,0 +1,40 @@
+import { Logger } from './services/logger.js'
+
+// TODO: SessionServices probably needs it's own type
+// but is an issue for the future and will be tackled
+// with dependency injection
+export const closeSessionServices = async (
+  logger: Logger,
+  sessionServices: Record<string, any>
+) => {
+  await Promise.all(
+    Object.values(sessionServices).map(async (service) => {
+      if (service?.close) {
+        try {
+          await service.close()
+        } catch (e: any) {
+          logger.error(e)
+        }
+      }
+    })
+  )
+}
+
+export const createWeakUID = () => {
+  return Date.now().toString(36) + Math.random().toString(36).substring(2, 10)
+}
+
+export const isSerializable = (data: any): boolean => {
+  return !(
+    typeof data === 'string' ||
+    data instanceof ArrayBuffer ||
+    data instanceof Uint8Array ||
+    data instanceof Int8Array ||
+    data instanceof Uint16Array ||
+    data instanceof Int16Array ||
+    data instanceof Uint32Array ||
+    data instanceof Int32Array ||
+    data instanceof Float32Array ||
+    data instanceof Float64Array
+  )
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "composite": true,
+    "module": "Node16",
+    "outDir": "dist",
+    "target": "esnext",
+    "moduleResolution": "node16"
+  },
+  "exclude": ["**/*.test.ts", "node_modules", "dist"],
+  "references": []
+}