@c9up/ream 0.1.3

package/src/helpers/is.ts

@@ -0,0 +1,162 @@
+/**
+ * Returns true if value is a string.
+ * @example isString('hi') // true
+ */
+export function isString(v: unknown): v is string {
+  return typeof v === 'string'
+}
+
+/**
+ * Returns true if value is a finite number (excludes NaN).
+ * @example isNumber(42) // true; isNumber(NaN) // false
+ */
+export function isNumber(v: unknown): v is number {
+  return typeof v === 'number' && !Number.isNaN(v)
+}
+
+/**
+ * Returns true if value is a boolean.
+ * @example isBoolean(true) // true
+ */
+export function isBoolean(v: unknown): v is boolean {
+  return typeof v === 'boolean'
+}
+
+/**
+ * Returns true if value is a callable function.
+ * @example isFunction(() => {}) // true
+ */
+export function isFunction(v: unknown): v is (...args: unknown[]) => unknown {
+  return typeof v === 'function'
+}
+
+/**
+ * Returns true if value is a non-null object.
+ * @example isObject({}) // true; isObject(null) // false
+ */
+export function isObject(v: unknown): v is object {
+  return v !== null && typeof v === 'object'
+}
+
+/**
+ * Returns true if value is a plain object (non-null, non-array, prototype is Object or null).
+ * @example isPlainObject({ a: 1 }) // true; isPlainObject([]) // false
+ */
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  if (v === null || typeof v !== 'object') return false
+  if (Array.isArray(v)) return false
+  const proto = Object.getPrototypeOf(v) as unknown
+  return proto === null || proto === Object.prototype
+}
+
+/**
+ * Returns true if value is an array.
+ * @example isArray([1, 2]) // true
+ */
+export function isArray<T = unknown>(v: unknown): v is T[] {
+  return Array.isArray(v)
+}
+
+/**
+ * Returns true if value has a thenable interface (is a Promise or promise-like).
+ * @example isPromise(Promise.resolve()) // true
+ */
+export function isPromise<T = unknown>(v: unknown): v is Promise<T> {
+  return (
+    v !== null &&
+    typeof v === 'object' &&
+    'then' in v &&
+    typeof (v as Record<string, unknown>).then === 'function'
+  )
+}
+
+/**
+ * Returns true if value is null.
+ * @example isNull(null) // true
+ */
+export function isNull(v: unknown): v is null {
+  return v === null
+}
+
+/**
+ * Returns true if value is undefined.
+ * @example isUndefined(undefined) // true
+ */
+export function isUndefined(v: unknown): v is undefined {
+  return v === undefined
+}
+
+/**
+ * Returns true if value is null or undefined.
+ * @example isNullOrUndefined(null) // true; isNullOrUndefined(undefined) // true
+ */
+export function isNullOrUndefined(v: unknown): v is null | undefined {
+  return v === null || v === undefined
+}
+
+/**
+ * Returns true if value is a Node.js Buffer.
+ * @example isBuffer(Buffer.from('hi')) // true
+ */
+export function isBuffer(v: unknown): v is Buffer {
+  return Buffer.isBuffer(v)
+}
+
+/**
+ * Returns true if value is a Date object.
+ * @example isDate(new Date()) // true
+ */
+export function isDate(v: unknown): v is Date {
+  return v instanceof Date
+}
+
+/**
+ * Returns true if value is a RegExp.
+ * @example isRegExp(/foo/) // true
+ */
+export function isRegExp(v: unknown): v is RegExp {
+  return v instanceof RegExp
+}
+
+/**
+ * Returns true if value is an Error instance.
+ * @example isError(new Error()) // true
+ */
+export function isError(v: unknown): v is Error {
+  return v instanceof Error
+}
+
+/**
+ * Returns true for null, undefined, empty string, empty array, empty plain object,
+ * empty Map, or empty Set.
+ * @example isEmpty('') // true; isEmpty([]) // true; isEmpty({}) // true
+ */
+export function isEmpty(v: unknown): boolean {
+  if (v === null || v === undefined) return true
+  if (typeof v === 'string') return v.length === 0
+  if (Array.isArray(v)) return v.length === 0
+  if (v instanceof Map || v instanceof Set) return v.size === 0
+  if (isPlainObject(v)) return Object.keys(v).length === 0
+  return false
+}
+
+const is = {
+  isString,
+  isNumber,
+  isBoolean,
+  isFunction,
+  isObject,
+  isPlainObject,
+  isArray,
+  isPromise,
+  isNull,
+  isUndefined,
+  isNullOrUndefined,
+  isBuffer,
+  isDate,
+  isRegExp,
+  isError,
+  isEmpty,
+}
+
+export default is

package/src/helpers/napi-loader.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared NAPI binary loader. Every `.node` file distributed with
+ * `@c9up/ream` uses the same platform-suffix convention and lookup
+ * strategy — extracting this helper avoids drift between the three
+ * call sites (HyperServer, Scheduler, and future NAPI consumers) and
+ * matches the codex review's "stop duplicating native loaders"
+ * guidance.
+ */
+
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { arch, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { ReamError } from '../errors/ReamError.js'
+
+/** Platform triple suffix (matches napi-rs naming). */
+export const NAPI_PLATFORM_MAP: Record<string, string> = {
+  'linux-x64': 'linux-x64-gnu',
+  'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64',
+  'darwin-arm64': 'darwin-arm64',
+  'win32-x64': 'win32-x64-msvc',
+}
+
+export interface LoadNapiOptions {
+  /**
+   * Base filename of the `.node` binary (without the platform suffix
+   * or `.node` extension). E.g. `"index"` for HyperServer,
+   * `"scheduler"` for the Ream scheduler.
+   */
+  binaryName: string
+  /**
+   * Caller's `import.meta.url` — used to compute the candidate paths
+   * relative to the caller's module location.
+   */
+  callerMetaUrl: string
+  /**
+   * Error-code prefix used to build `<PREFIX>_NAPI_NOT_FOUND`,
+   * `<PREFIX>_NAPI_LOAD_FAILED`, and `<PREFIX>_UNSUPPORTED_PLATFORM`
+   * codes when loading fails. E.g. `"SCHEDULER"`.
+   */
+  errorCodePrefix: string
+  /** Hint appended to the "not found" error (typically a build command). */
+  notFoundHint?: string
+}
+
+/**
+ * Resolve and `require` a Ream NAPI binary, returning the native
+ * module export. Throws a typed `ReamError` on any failure.
+ *
+ * Search order (first hit wins):
+ *   1. `<caller>/../../<binaryName>.<suffix>.node`
+ *   2. `<caller>/../<binaryName>.<suffix>.node`
+ *   3. `<caller>/<binaryName>.<suffix>.node`
+ *
+ * The three-level fallback matches the layout where the compiled
+ * `.node` sits either at the package root, a subdirectory, or next to
+ * the calling module.
+ */
+export function loadNapi<T>(options: LoadNapiOptions): T {
+  const { binaryName, callerMetaUrl, errorCodePrefix } = options
+  const suffix = NAPI_PLATFORM_MAP[`${platform}-${arch}`]
+  if (!suffix) {
+    throw new ReamError(
+      `${errorCodePrefix}_UNSUPPORTED_PLATFORM`,
+      `Unsupported platform: ${platform}-${arch}`,
+    )
+  }
+
+  const req = createRequire(callerMetaUrl)
+  const dir = dirname(fileURLToPath(callerMetaUrl))
+  const candidates = [
+    join(dir, '..', '..', `${binaryName}.${suffix}.node`),
+    join(dir, '..', `${binaryName}.${suffix}.node`),
+    join(dir, `${binaryName}.${suffix}.node`),
+  ]
+
+  for (const path of candidates) {
+    try {
+      return req(path) as T
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException | undefined)?.code
+      if (code === 'MODULE_NOT_FOUND') continue
+      // Any other error (SyntaxError, ABI mismatch, permissions,
+      // corrupt binary) means the file exists but cannot load. Surface
+      // the real cause rather than a generic "not found".
+      throw new ReamError(
+        `${errorCodePrefix}_NAPI_LOAD_FAILED`,
+        `${binaryName} NAPI binary exists at '${path}' but failed to load: ${(e as Error).message}`,
+        {
+          hint: 'Check that the binary was built for the current platform and Node ABI. Rebuild with `pnpm --filter @c9up/ream build:rust`.',
+        },
+      )
+    }
+  }
+
+  throw new ReamError(
+    `${errorCodePrefix}_NAPI_NOT_FOUND`,
+    `${binaryName} NAPI binary not found. Expected ${binaryName}.${suffix}.node`,
+    {
+      hint:
+        options.notFoundHint ??
+        "Run 'pnpm --filter @c9up/ream build:rust' to build the native module.",
+    },
+  )
+}

package/src/helpers/safeEqual.ts

@@ -0,0 +1,15 @@
+import { timingSafeEqual } from 'node:crypto'
+
+/**
+ * Timing-safe comparison of two strings or buffers. Prevents timing attacks.
+ *
+ * @example
+ * safeEqual('secret', 'secret') // true
+ * safeEqual('secret', 'wrong')  // false
+ */
+export function safeEqual(a: string | Buffer, b: string | Buffer): boolean {
+  const bufA = typeof a === 'string' ? Buffer.from(a) : a
+  const bufB = typeof b === 'string' ? Buffer.from(b) : b
+  if (bufA.length !== bufB.length) return false
+  return timingSafeEqual(bufA, bufB)
+}