@yamf/services-postgres 0.1.2

package/README.md

@@ -0,0 +1,97 @@
+# @yamf/services-postgres
+
+Postgres.js wrapper for YAMF: parameterized SQL templates, camelCase result mapping, and safe placeholder validation.
+
+[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)]()
+[![License](https://img.shields.io/badge/license-MIT-blue)]()
+
+## Installation
+
+```bash
+npm install @yamf/services-postgres
+```
+
+Peer dependencies: `@yamf/core`, `@yamf/shared`. The package uses [postgres](https://github.com/porsager/postgres) (`postgres` npm package).
+
+## Quick Start
+
+```javascript
+import { registryServer, createService, callService } from '@yamf/core'
+import createPostgreSqlService from '@yamf/services-postgres'
+
+await registryServer()
+
+const postgres = await createPostgreSqlService({
+  serviceName: 'postgres-service',
+  psqlConfig: 'postgres://user:pass@localhost/dbname'
+  // or: { PGDATABASE: 'yamf', PGUSER: 'yamf', PGPASSWORD: 'changeme' }
+})
+
+// Call from another service or gateway
+const [row] = await callService('postgres-service', {
+  template: `SELECT user_id, username, is_active FROM yamf.user WHERE username = :username`,
+  data: { username: 'alice@example.com' }
+})
+// row has camelCase keys: userId, username, isActive
+```
+
+## Features
+
+- **Parameterized queries** – Template placeholders `:name` are replaced with safe parameters; no string interpolation of user input.
+- **CamelCase mapping** – Result rows are converted from `snake_case` to camelCase by default (via `@yamf/shared`).
+- **Placeholder validation** – Only valid identifiers are allowed for placeholder names to prevent injection.
+- **Postgres.js** – Uses [postgres](https://github.com/porsager/postgres) under the hood.
+
+## API
+
+### `createPostgreSqlService(options)`
+
+| Option        | Default             | Description |
+|---------------|---------------------|-------------|
+| `serviceName` | `'postgres-service'` | YAMF service name to register. |
+| `psqlConfig`  | env / `{ PGDATABASE, PGUSER, PGPASSWORD }` | Postgres connection string or config object. |
+| `schema`      | `null`              | Optional schema setup. |
+| `seed`        | `null`              | Optional seed logic. |
+
+### Payload
+
+Call the service with:
+
+- **`template`** (string) – SQL with `:placeholder` names in camelCase (e.g. `:userId`, `:isActive`).
+- **`data`** (object) – Keys match placeholder names (camelCase). All placeholders must have a value.
+- **`options`** (optional) – e.g. `{ mapCase: true }` (default). Set `mapCase: false` to skip camelCase conversion.
+
+Returns the result of the query (array of rows, or raw result from postgres.js). With `mapCase: true`, row keys are camelCase.
+
+## Template and data
+
+- Use **camelCase** for placeholder names in the template and for keys in `data`: `:userId`, `:username`, `:isActive`.
+- Write **snake_case** in SQL as usual: `user_id`, `username`, `is_active`.
+- Only valid identifier names are allowed for placeholders (alphanumeric and underscore, no SQL injection via placeholder names).
+
+Example:
+
+```javascript
+await callService('postgres-service', {
+  template: `
+    SELECT user_id, username, is_registered, is_active
+    FROM yamf.user
+    WHERE user_id = :userId OR username = :username
+  `,
+  data: { userId: 1, username: 'alice@example.com' }
+})
+```
+
+## Using with other services
+
+This service is the data layer for **@yamf/services-user** and for custom auth (e.g. looking up users and verifying passwords). For a full example that wires Postgres + User + Auth together, see the [psql-user-auth example](../../core/examples/psql-user-auth/) in the repo.
+
+## Dependencies
+
+- `postgres` – Postgres.js driver
+- `@yamf/core` – createService, callService, HttpError
+- `@yamf/shared` – toCamelCase for result mapping
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@yamf/services-postgres",
+  "version": "0.1.2",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "service.js",
+  "files": [
+    "service.js",
+    "README.md"
+  ],
+  "dependencies": {
+    "postgres": "^3.4.8"
+  },
+  "peerDependencies": {
+    "@yamf/core": "0.4.0",
+    "@yamf/shared": "0.1.2"
+  },
+  "devDependencies": {
+    "@yamf/cli": "0.2.0",
+    "@yamf/test": "0.1.4"
+  },
+  "scripts": {
+    "test": "yamf test -d ."
+  }
+}

package/service.js

@@ -0,0 +1,109 @@
+import {
+  createService,
+  Logger,
+  HttpError,
+  next,
+  envConfig
+} from '@yamf/core'
+
+import postgres from 'postgres'
+import { toCamelCase } from '@yamf/shared'
+
+
+// requires a database, schema, and user all called "yamf"
+// make sure to grant the user permissions on the database and schema
+const defaultPsqlConfig = `postgres://yamf:changeme@localhost/yamf`
+
+// Strict pattern for placeholder names - only valid identifiers allowed
+const VALID_PLACEHOLDER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+/**
+ * Validates that a placeholder name is safe (alphanumeric + underscore, starts with letter/underscore)
+ * This prevents code injection through malicious placeholder names.
+ */
+function validatePlaceholderName(name) {
+  if (!VALID_PLACEHOLDER_PATTERN.test(name)) {
+    throw new HttpError(400, `Invalid placeholder name: "${name}". Must be a valid identifier.`)
+  }
+  return true
+}
+
+export default async function createPostgreSqlService({
+  serviceName = 'postgres-service',
+  psqlConfig = defaultPsqlConfig,
+  schema = null,
+  seed = null
+}) {
+  const sql = postgres(psqlConfig) // psql environment variables
+
+  /**
+   * Processes a template query string with provided data using safe parameterized queries.
+   * 
+   * SECURITY: This implementation avoids the dangerous `new Function()` pattern.
+   * Instead, it extracts placeholders, validates them strictly, and uses postgres.js's
+   * built-in parameterized query support which safely escapes all values.
+   * 
+   * Template placeholders use camelCase (e.g., :userId, :isActive) to match JS data keys.
+   * SQL column names in the template are written as snake_case by the developer.
+   * Output is automatically converted from snake_case to camelCase.
+   * 
+   * @param {string} template The string containing `:<name>` placeholders (camelCase).
+   * @param {object} data An object with camelCase keys corresponding to the placeholders.
+   * @param {object} options Query options.
+   * @param {boolean} options.mapCase Whether to convert output from snake_case to camelCase (default: true)
+   * @returns {Promise<Array>} The query result with camelCase keys.
+   */
+  async function processQueryTemplate(template, data, options) {
+    const { mapCase = true } = options || {}
+    
+    // Extract all placeholder names from template (placeholders are camelCase)
+    const placeholderMatches = [...template.matchAll(/(?<!:):([a-zA-Z_][a-zA-Z0-9_]*)/g)]
+    const placeholders = placeholderMatches.map(m => m[1])
+    
+    // Validate all placeholder names are safe identifiers
+    for (const name of placeholders) {
+      validatePlaceholderName(name)
+    }
+    
+    // Check all placeholders have corresponding data
+    for (const name of placeholders) {
+      if (!(name in data)) {
+        throw new HttpError(400, `Missing data for placeholder: "${name}"`)
+      }
+    }
+    
+    // Build the values array in placeholder order
+    const values = placeholders.map(name => data[name])
+    
+    // Replace :name placeholders with $1, $2, etc. for parameterized query
+    let paramIndex = 0
+    const parameterizedQuery = template.replace(/(?<!:):([a-zA-Z_][a-zA-Z0-9_]*)/g, () => {
+      return `$${++paramIndex}`
+    })
+    
+    try {
+      // Use sql.unsafe for the parameterized query - this is safe because:
+      // 1. The query structure is from our template (not user input in production)
+      // 2. All values are passed as parameters, never interpolated into the query string
+      // 3. postgres.js handles proper escaping of parameter values
+      const result = await sql.unsafe(parameterizedQuery, values)
+      
+      // Convert result keys from snake_case to camelCase for JS consumption
+      return mapCase ? toCamelCase(result) : result
+    } catch (err) {
+      const httpError = new HttpError(500, `Query error: ${err.message}`)
+      httpError.stack = err.stack
+      httpError.parameterizedQuery = parameterizedQuery
+      throw httpError
+    }
+  }
+
+
+  let service = await createService(serviceName, async ({ template, data, options }) => {
+    if (!template) throw new HttpError(400, 'Expected "template" query string in payload')
+    if (!data) throw new HttpError(400, 'Expected "data" map in payload')
+    return await processQueryTemplate(template, data, options)
+  })
+
+  return service
+}