@c9up/ream 0.1.24 → 0.1.26

package/src/utils/inflect.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal zero-dependency string inflection — the two operations resourceful
+ * routing needs from AdonisJS's `@poppinss/utils/string`: `snakeCase` (route
+ * name normalisation) and `singular` (nested-resource param naming, `photos`
+ * → `photo_id`).
+ *
+ * Deviation from AdonisJS (named): `singular` covers regular English plurals
+ * only (`-ies→-y`, `-(s|x|z|ch|sh)es→drop es`, trailing `-s→drop`). Irregular
+ * plurals (`people→person`, `geese→goose`) are NOT handled — resource names in
+ * REST APIs are overwhelmingly regular, and a full inflector (irregular tables,
+ * uncountables) would be a dependency-sized rabbit hole for a niche case.
+ */
+
+/** Convert `camelCase`/`PascalCase`/`kebab-case`/spaced text to `snake_case`. */
+export function snakeCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[-\s]+/g, '_')
+    .toLowerCase()
+}
+
+/** Singularize a regular English plural (see module deviation note). */
+export function singular(word: string): string {
+  if (word.length > 3 && /ies$/i.test(word)) return word.replace(/ies$/i, 'y')
+  if (/(?:s|x|z|ch|sh)es$/i.test(word)) return word.replace(/es$/i, '')
+  if (/ss$/i.test(word)) return word
+  if (/s$/i.test(word)) return word.replace(/s$/i, '')
+  return word
+}

package/src/utils/objectPath.ts

@@ -0,0 +1,142 @@
+/**
+ * Zero-dependency dot-path object access — the small subset of `lodash`
+ * (`get`/`set`/`has`/`pick`/`omit`/`merge`) that Config and Request need for
+ * AdonisJS-parity nested access (`config.get('database.mysql.host')`,
+ * `request.input('user.address.city')`).
+ *
+ * AdonisJS uses `@poppinss/utils/lodash` for this. Ream stays lean and
+ * dependency-free (same stance as aurora's hand-written `cn`/`clsx`), so we
+ * reimplement exactly the four semantics we rely on — no more.
+ *
+ * Path syntax: `a.b.c` and `a[0].c` / `a.0.c` (bracket + dotted indices) are
+ * both accepted, matching lodash's tokenizer for the shapes config/request
+ * data actually take (plain JSON objects and arrays).
+ */
+
+/** A JSON-ish record we can index by string key. */
+type UnknownRecord = Record<string, unknown>
+
+/** True for plain objects and arrays (anything indexable by a path segment). */
+function isIndexable(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null
+}
+
+/**
+ * Split a dot/bracket path into segments: `a.b[0].c` → `['a','b','0','c']`.
+ * A single already-simple key (no `.`/`[`) is returned as-is, so keys that
+ * happen to contain neither delimiter cost nothing.
+ */
+function toSegments(path: string): string[] {
+  if (path.indexOf('.') === -1 && path.indexOf('[') === -1) return [path]
+  const segments: string[] = []
+  const matcher = /[^.[\]]+/g
+  let match: RegExpExecArray | null = matcher.exec(path)
+  while (match !== null) {
+    segments.push(match[0])
+    match = matcher.exec(path)
+  }
+  return segments
+}
+
+/**
+ * Read a nested value by dot-path. Returns `defaultValue` when any segment is
+ * missing or the resolved value is `undefined` (lodash.get semantics).
+ */
+export function getPath(source: unknown, path: string, defaultValue?: unknown): unknown {
+  const segments = toSegments(path)
+  let current: unknown = source
+  for (const segment of segments) {
+    if (!isIndexable(current)) return defaultValue
+    current = current[segment]
+  }
+  return current === undefined ? defaultValue : current
+}
+
+/**
+ * True when the full dot-path exists on `source` (each segment is an own key),
+ * even if the leaf value is `undefined` (lodash.has semantics).
+ */
+export function hasPath(source: unknown, path: string): boolean {
+  const segments = toSegments(path)
+  let current: unknown = source
+  for (const segment of segments) {
+    if (!isIndexable(current) || !Object.hasOwn(current, segment)) return false
+    current = current[segment]
+  }
+  return true
+}
+
+/**
+ * Set a nested value by dot-path, creating intermediate plain objects as
+ * needed, and return the (mutated) root.
+ *
+ * Deviation from lodash.set (named): integer segments create plain objects,
+ * NOT arrays. Config trees and request-data picks are keyed objects; ream
+ * never sets array indices through a path, so array auto-vivification would be
+ * dead behaviour.
+ */
+export function setPath(target: UnknownRecord, path: string, value: unknown): UnknownRecord {
+  const segments = toSegments(path)
+  let current: UnknownRecord = target
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    const key = segments[i]
+    const next = current[key]
+    if (!isIndexable(next)) {
+      const created: UnknownRecord = {}
+      current[key] = created
+      current = created
+    } else {
+      current = next
+    }
+  }
+  current[segments[segments.length - 1]] = value
+  return target
+}
+
+/**
+ * Return a new object containing only the given dot-paths (lodash.pick).
+ * Missing paths are skipped; nested paths reconstruct their branch, so
+ * `pickPaths({a:{b:1,c:2}}, ['a.b'])` yields `{a:{b:1}}`.
+ */
+export function pickPaths(source: unknown, paths: string[]): UnknownRecord {
+  const result: UnknownRecord = {}
+  for (const path of paths) {
+    if (hasPath(source, path)) setPath(result, path, getPath(source, path))
+  }
+  return result
+}
+
+/**
+ * Return a deep clone of `source` with the given dot-paths removed
+ * (lodash.omit). Operates on JSON-ish data (body + query), so `structuredClone`
+ * is a safe deep copy that never mutates the caller's input.
+ */
+export function omitPaths(source: UnknownRecord, paths: string[]): UnknownRecord {
+  const result = structuredClone(source)
+  for (const path of paths) {
+    const segments = toSegments(path)
+    let current: unknown = result
+    for (let i = 0; i < segments.length - 1; i += 1) {
+      if (!isIndexable(current)) break
+      current = current[segments[i]]
+    }
+    if (isIndexable(current)) delete current[segments[segments.length - 1]]
+  }
+  return result
+}
+
+/**
+ * Deep-merge `source` over `target` (recursively for nested plain objects;
+ * scalars and arrays from `source` replace `target`). Returns a new object;
+ * neither input is mutated. Backs `Config.defaults` — the AdonisJS semantics
+ * where existing config wins over provided defaults.
+ */
+export function mergeDeep(target: unknown, source: unknown): unknown {
+  if (!isIndexable(target) || Array.isArray(target)) return source === undefined ? target : source
+  if (!isIndexable(source) || Array.isArray(source)) return source === undefined ? target : source
+  const out: UnknownRecord = { ...target }
+  for (const key of Object.keys(source)) {
+    out[key] = mergeDeep(out[key], source[key])
+  }
+  return out
+}

package/dist/decorators/Lazy.d.ts

@@ -1,19 +0,0 @@
-/**
- * @Lazy() decorator — deferred injection to break circular dependencies.
- *
- * @implements FR15
- */
-import 'reflect-metadata';
-/**
- * @Lazy() — marks a constructor parameter for deferred resolution.
- * The dependency is resolved on first property access, not at construction.
- */
-export declare function Lazy(): ParameterDecorator;
-/** Get lazy parameter indices for a constructor. */
-export declare function getLazyParams(target: object): number[];
-/**
- * Create a lazy proxy that defers resolution until first access.
- * Traps get, set, has, ownKeys, getOwnPropertyDescriptor for full compatibility.
- */
-export declare function createLazyProxy<T extends object>(resolver: () => T): T;
-//# sourceMappingURL=Lazy.d.ts.map

package/dist/decorators/Lazy.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Lazy.d.ts","sourceRoot":"","sources":["../../src/decorators/Lazy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,kBAAkB,CAAA;AAIzB;;;GAGG;AACH,wBAAgB,IAAI,IAAI,kBAAkB,CAMzC;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAyBtE"}

package/dist/decorators/Lazy.js

@@ -1,53 +0,0 @@
-/**
- * @Lazy() decorator — deferred injection to break circular dependencies.
- *
- * @implements FR15
- */
-import 'reflect-metadata';
-const LAZY_KEY = Symbol.for('ream:lazy');
-/**
- * @Lazy() — marks a constructor parameter for deferred resolution.
- * The dependency is resolved on first property access, not at construction.
- */
-export function Lazy() {
-    return (target, propertyKey, parameterIndex) => {
-        const existing = Reflect.getOwnMetadata(LAZY_KEY, target, propertyKey ?? '') ?? [];
-        existing.push(parameterIndex);
-        Reflect.defineMetadata(LAZY_KEY, existing, target, propertyKey ?? '');
-    };
-}
-/** Get lazy parameter indices for a constructor. */
-export function getLazyParams(target) {
-    return Reflect.getOwnMetadata(LAZY_KEY, target, '') ?? [];
-}
-/**
- * Create a lazy proxy that defers resolution until first access.
- * Traps get, set, has, ownKeys, getOwnPropertyDescriptor for full compatibility.
- */
-export function createLazyProxy(resolver) {
-    let instance;
-    const ensure = () => {
-        if (!instance)
-            instance = resolver();
-        return instance;
-    };
-    // biome-ignore lint/suspicious/noExplicitAny: Proxy target must be an object literal; T is branded at call site
-    return new Proxy({}, {
-        get(_target, prop, receiver) {
-            return Reflect.get(ensure(), prop, receiver);
-        },
-        set(_target, prop, value, receiver) {
-            return Reflect.set(ensure(), prop, value, receiver);
-        },
-        has(_target, prop) {
-            return Reflect.has(ensure(), prop);
-        },
-        ownKeys() {
-            return Reflect.ownKeys(ensure());
-        },
-        getOwnPropertyDescriptor(_target, prop) {
-            return Object.getOwnPropertyDescriptor(ensure(), prop);
-        },
-    });
-}
-//# sourceMappingURL=Lazy.js.map

package/dist/decorators/Lazy.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Lazy.js","sourceRoot":"","sources":["../../src/decorators/Lazy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,kBAAkB,CAAA;AAEzB,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;AAExC;;;GAGG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;QAC7C,MAAM,QAAQ,GAAa,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;QAC5F,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAC7B,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,IAAI,EAAE,CAAC,CAAA;IACvE,CAAC,CAAA;AACH,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,CAAA;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAmB,QAAiB;IACjE,IAAI,QAAuB,CAAA;IAC3B,MAAM,MAAM,GAAG,GAAM,EAAE;QACrB,IAAI,CAAC,QAAQ;YAAE,QAAQ,GAAG,QAAQ,EAAE,CAAA;QACpC,OAAO,QAAQ,CAAA;IACjB,CAAC,CAAA;IAED,gHAAgH;IAChH,OAAO,IAAI,KAAK,CAAC,EAAc,EAAE;QAC/B,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ;YACzB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;QAC9C,CAAC;QACD,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ;YAChC,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAA;QACrD,CAAC;QACD,GAAG,CAAC,OAAO,EAAE,IAAI;YACf,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,CAAA;QACpC,CAAC;QACD,OAAO;YACL,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QAClC,CAAC;QACD,wBAAwB,CAAC,OAAO,EAAE,IAAI;YACpC,OAAO,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,CAAA;QACxD,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/src/decorators/Lazy.ts

@@ -1,57 +0,0 @@
-/**
- * @Lazy() decorator — deferred injection to break circular dependencies.
- *
- * @implements FR15
- */
-
-import 'reflect-metadata'
-
-const LAZY_KEY = Symbol.for('ream:lazy')
-
-/**
- * @Lazy() — marks a constructor parameter for deferred resolution.
- * The dependency is resolved on first property access, not at construction.
- */
-export function Lazy(): ParameterDecorator {
-  return (target, propertyKey, parameterIndex) => {
-    const existing: number[] = Reflect.getOwnMetadata(LAZY_KEY, target, propertyKey ?? '') ?? []
-    existing.push(parameterIndex)
-    Reflect.defineMetadata(LAZY_KEY, existing, target, propertyKey ?? '')
-  }
-}
-
-/** Get lazy parameter indices for a constructor. */
-export function getLazyParams(target: object): number[] {
-  return Reflect.getOwnMetadata(LAZY_KEY, target, '') ?? []
-}
-
-/**
- * Create a lazy proxy that defers resolution until first access.
- * Traps get, set, has, ownKeys, getOwnPropertyDescriptor for full compatibility.
- */
-export function createLazyProxy<T extends object>(resolver: () => T): T {
-  let instance: T | undefined
-  const ensure = (): T => {
-    if (!instance) instance = resolver()
-    return instance
-  }
-
-  // biome-ignore lint/suspicious/noExplicitAny: Proxy target must be an object literal; T is branded at call site
-  return new Proxy({} as any as T, {
-    get(_target, prop, receiver) {
-      return Reflect.get(ensure(), prop, receiver)
-    },
-    set(_target, prop, value, receiver) {
-      return Reflect.set(ensure(), prop, value, receiver)
-    },
-    has(_target, prop) {
-      return Reflect.has(ensure(), prop)
-    },
-    ownKeys() {
-      return Reflect.ownKeys(ensure())
-    },
-    getOwnPropertyDescriptor(_target, prop) {
-      return Object.getOwnPropertyDescriptor(ensure(), prop)
-    },
-  })
-}