@pthm/melange 0.4.0 → 0.6.4

package/README.md

@@ -2,43 +2,319 @@
 
 TypeScript client for Melange PostgreSQL authorization.
 
-> **Note:** This package is a placeholder. The TypeScript runtime is not yet implemented.
-> Use the Go runtime (`github.com/pthm/melange/melange`) for production workloads.
+Melange is an OpenFGA-compatible authorization library that runs entirely in PostgreSQL. This TypeScript client provides type-safe access to the authorization system.
 
 ## Installation
 
 ```bash
-npm install @pthm/melange
+npm install @pthm/melange pg
+# or
+yarn add @pthm/melange pg
+# or
+pnpm add @pthm/melange pg
 ```
 
-## Status
+## Quick Start
 
-This package provides:
-- Type definitions for authorization objects
-- Placeholder Checker class (throws "not implemented")
+```typescript
+import { Checker } from '@pthm/melange';
+import { Pool } from 'pg';
 
-The full implementation will include:
-- `Checker` class for permission checks
-- `Cache` for caching decisions
-- Connection pooling support
+// Create a PostgreSQL connection pool
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+});
+
+// Create a checker instance
+const checker = new Checker(pool);
+
+// Perform a permission check
+const decision = await checker.check(
+  { type: 'user', id: '123' },
+  'can_read',
+  { type: 'repository', id: '456' }
+);
+
+if (decision.allowed) {
+  console.log('Access granted!');
+} else {
+  console.log('Access denied.');
+}
+```
+
+## Features
+
+### Permission Checks
+
+```typescript
+// Check if a user can read a repository
+const decision = await checker.check(
+  { type: 'user', id: '123' },
+  'can_read',
+  { type: 'repository', id: '456' }
+);
+```
+
+### List Operations
+
+```typescript
+// List all repositories a user can read
+const result = await checker.listObjects(
+  { type: 'user', id: '123' },
+  'can_read',
+  'repository',
+  { limit: 100 }
+);
+
+for (const repoId of result.items) {
+  console.log(`Repository: ${repoId}`);
+}
+
+// List all users who can read a repository
+const users = await checker.listSubjects(
+  'user',
+  'can_read',
+  { type: 'repository', id: '456' },
+  { limit: 100 }
+);
+```
+
+### Caching
+
+```typescript
+import { Checker, MemoryCache } from '@pthm/melange';
+
+// Create a checker with caching
+const cache = new MemoryCache(60000); // 60 second TTL
+const checker = new Checker(pool, { cache });
+
+// First check hits the database
+await checker.check(user, 'can_read', repo);
+
+// Second check within 60s uses the cache
+await checker.check(user, 'can_read', repo); // cached
+```
+
+### Decision Overrides for Testing
+
+```typescript
+import { Checker, DecisionAllow, DecisionDeny } from '@pthm/melange';
+
+// Test authorized paths
+const allowChecker = new Checker(pool, { decision: DecisionAllow });
+await allowChecker.check(user, 'can_read', repo); // always returns { allowed: true }
+
+// Test unauthorized paths
+const denyChecker = new Checker(pool, { decision: DecisionDeny });
+await denyChecker.check(user, 'can_read', repo); // always returns { allowed: false }
+```
+
+### Contextual Tuples
+
+```typescript
+// Check with temporary permissions
+const decision = await checker.checkWithContextualTuples(
+  { type: 'user', id: '123' },
+  'can_read',
+  { type: 'document', id: '789' },
+  [
+    {
+      subject: { type: 'user', id: '123' },
+      relation: 'temp_access',
+      object: { type: 'document', id: '789' }
+    }
+  ]
+);
+```
+
+## Database Adapters
+
+The runtime works with any PostgreSQL client that implements the `Queryable` interface:
+
+```typescript
+interface Queryable {
+  query<T>(text: string, params?: any[]): Promise<{ rows: T[] }>;
+}
+```
+
+### node-postgres (pg)
+
+node-postgres Pool and Client already implement `Queryable` and can be used directly:
+
+```typescript
+import { Checker } from '@pthm/melange';
+import { Pool } from 'pg';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const checker = new Checker(pool); // Works directly
+```
+
+### postgres.js
+
+Use the `postgresAdapter` to wrap a postgres.js instance:
+
+```typescript
+import postgres from 'postgres';
+import { Checker, postgresAdapter } from '@pthm/melange';
+
+const sql = postgres(process.env.DATABASE_URL);
+const checker = new Checker(postgresAdapter(sql));
+```
 
 ## Generated Client Code
 
-You can generate type-safe client code from your schema using the melange CLI:
+Generate type-safe constants and factory functions from your schema:
 
 ```bash
 melange generate client --runtime typescript --schema schema.fga --output ./src/authz/
 ```
 
-This generates:
-- Type constants (`TYPE_USER`, `TYPE_REPOSITORY`)
-- Relation constants (`REL_CAN_READ`, `REL_OWNER`)
-- Factory functions (`user()`, `repository()`)
+This generates three files:
 
-## Contributing
+### types.ts
 
-See the [main repository](https://github.com/pthm/melange) for contribution guidelines.
+```typescript
+export const ObjectTypes = {
+  User: "user",
+  Repository: "repository",
+} as const;
+
+export type ObjectType = (typeof ObjectTypes)[keyof typeof ObjectTypes];
+
+export const Relations = {
+  CanRead: "can_read",
+  Owner: "owner",
+} as const;
+
+export type Relation = (typeof Relations)[keyof typeof Relations];
+```
+
+### schema.ts
+
+```typescript
+import type { MelangeObject } from '@pthm/melange';
+import { ObjectTypes } from './types.js';
+
+export function user(id: string): MelangeObject {
+  return { type: ObjectTypes.User, id };
+}
+
+export function repository(id: string): MelangeObject {
+  return { type: ObjectTypes.Repository, id };
+}
+
+export function anyUser(): MelangeObject {
+  return { type: ObjectTypes.User, id: '*' };
+}
+```
+
+### Usage
+
+```typescript
+import { Checker } from '@pthm/melange';
+import { user, repository, Relations } from './authz/index.js';
+
+const decision = await checker.check(
+  user('123'),
+  Relations.CanRead,
+  repository('456')
+);
+```
+
+## API Reference
+
+### Checker
+
+```typescript
+class Checker {
+  constructor(db: Queryable, options?: CheckerOptions);
+
+  check(
+    subject: MelangeObject,
+    relation: Relation,
+    object: MelangeObject,
+    contextualTuples?: ContextualTuple[]
+  ): Promise<Decision>;
+
+  listObjects(
+    subject: MelangeObject,
+    relation: Relation,
+    objectType: ObjectType,
+    options?: PageOptions
+  ): Promise<ListResult<string>>;
+
+  listSubjects(
+    subjectType: ObjectType,
+    relation: Relation,
+    object: MelangeObject,
+    options?: PageOptions
+  ): Promise<ListResult<string>>;
+
+  checkWithContextualTuples(
+    subject: MelangeObject,
+    relation: Relation,
+    object: MelangeObject,
+    contextualTuples: ContextualTuple[]
+  ): Promise<Decision>;
+}
+```
+
+### CheckerOptions
+
+```typescript
+interface CheckerOptions {
+  cache?: Cache;                // Default: NoopCache
+  decision?: Decision;          // For testing only
+  validateRequest?: boolean;    // Default: true
+  validateUserset?: boolean;    // Default: true
+}
+```
+
+### Cache
+
+```typescript
+interface Cache {
+  get(key: string): Promise<Decision | undefined>;
+  set(key: string, value: Decision): Promise<void>;
+  clear(): Promise<void>;
+}
+
+class NoopCache implements Cache { }  // No caching
+class MemoryCache implements Cache {  // In-memory with TTL
+  constructor(ttlMs?: number);
+}
+```
+
+## Error Handling
+
+```typescript
+import { MelangeError, ValidationError, NotFoundError } from '@pthm/melange';
+
+try {
+  await checker.check(user, 'can_read', repo);
+} catch (err) {
+  if (err instanceof ValidationError) {
+    console.error('Invalid input:', err.message);
+  } else if (err instanceof NotFoundError) {
+    console.error('Resource not found:', err.message);
+  } else if (err instanceof MelangeError) {
+    console.error('Melange error:', err.message);
+  } else {
+    console.error('Unknown error:', err);
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18 or higher
+- PostgreSQL 14 or higher
+- Melange schema and functions installed in your database
 
 ## License
 
 MIT
+
+## Contributing
+
+See the [main repository](https://github.com/pthm/melange) for contribution guidelines.

package/dist/adapters/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Database adapters for Melange.
+ *
+ * This module provides adapters for popular PostgreSQL clients.
+ */
+export { pgAdapter } from './pg.js';
+export type { PgQueryable } from './pg.js';
+export { postgresAdapter } from './postgres.js';
+export type { PostgresSql } from './postgres.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,8 @@
+/**
+ * Database adapters for Melange.
+ *
+ * This module provides adapters for popular PostgreSQL clients.
+ */
+export { pgAdapter } from './pg.js';
+export { postgresAdapter } from './postgres.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/adapters/pg.d.ts

@@ -0,0 +1,42 @@
+/**
+ * node-postgres (pg) adapter for Melange.
+ *
+ * This module provides an adapter to use node-postgres Pool or Client
+ * with the Melange Checker.
+ */
+import type { Queryable } from '../database.js';
+/**
+ * PgQueryable represents a node-postgres client that can execute queries.
+ *
+ * This interface matches the query signature of both Pool and Client from 'pg'.
+ */
+export interface PgQueryable {
+    query<T = any>(text: string, params?: any[]): Promise<{
+        rows: T[];
+    }>;
+}
+/**
+ * pgAdapter wraps a node-postgres Pool or Client for use with Checker.
+ *
+ * Note: In most cases, you don't need this adapter. The pg Pool and Client
+ * already implement the Queryable interface and can be used directly.
+ *
+ * This adapter is provided for explicit type conversion if needed.
+ *
+ * @param client - A pg Pool or Client
+ * @returns A Queryable instance
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { Checker, pgAdapter } from '@pthm/melange';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const checker = new Checker(pgAdapter(pool));
+ *
+ * // Or use the pool directly (preferred):
+ * const checker = new Checker(pool);
+ * ```
+ */
+export declare function pgAdapter(client: PgQueryable): Queryable;
+//# sourceMappingURL=pg.d.ts.map

package/dist/adapters/pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.d.ts","sourceRoot":"","sources":["../../src/adapters/pg.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAOxD"}

package/dist/adapters/pg.js

@@ -0,0 +1,38 @@
+/**
+ * node-postgres (pg) adapter for Melange.
+ *
+ * This module provides an adapter to use node-postgres Pool or Client
+ * with the Melange Checker.
+ */
+/**
+ * pgAdapter wraps a node-postgres Pool or Client for use with Checker.
+ *
+ * Note: In most cases, you don't need this adapter. The pg Pool and Client
+ * already implement the Queryable interface and can be used directly.
+ *
+ * This adapter is provided for explicit type conversion if needed.
+ *
+ * @param client - A pg Pool or Client
+ * @returns A Queryable instance
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { Checker, pgAdapter } from '@pthm/melange';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const checker = new Checker(pgAdapter(pool));
+ *
+ * // Or use the pool directly (preferred):
+ * const checker = new Checker(pool);
+ * ```
+ */
+export function pgAdapter(client) {
+    return {
+        async query(text, params) {
+            const result = await client.query(text, params);
+            return { rows: result.rows };
+        },
+    };
+}
+//# sourceMappingURL=pg.js.map

package/dist/adapters/pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg.js","sourceRoot":"","sources":["../../src/adapters/pg.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,SAAS,CAAC,MAAmB;IAC3C,OAAO;QACL,KAAK,CAAC,KAAK,CAAU,IAAY,EAAE,MAAc;YAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC;YACnD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,37 @@
+/**
+ * postgres.js adapter for Melange.
+ *
+ * This module provides an adapter to use postgres.js with the Melange Checker.
+ */
+import type { Queryable } from '../database.js';
+/**
+ * PostgresSql represents a postgres.js Sql instance.
+ *
+ * This is a minimal interface matching postgres.js's unsafe method.
+ */
+export interface PostgresSql {
+    unsafe<T = any>(text: string, params?: any[]): Promise<T[]>;
+}
+/**
+ * postgresAdapter wraps a postgres.js Sql instance for use with Checker.
+ *
+ * @param sql - A postgres.js Sql instance
+ * @returns A Queryable instance
+ *
+ * @example
+ * ```typescript
+ * import postgres from 'postgres';
+ * import { Checker, postgresAdapter } from '@pthm/melange';
+ *
+ * const sql = postgres(process.env.DATABASE_URL);
+ * const checker = new Checker(postgresAdapter(sql));
+ *
+ * const decision = await checker.check(
+ *   { type: 'user', id: '123' },
+ *   'can_read',
+ *   { type: 'repository', id: '456' }
+ * );
+ * ```
+ */
+export declare function postgresAdapter(sql: PostgresSql): Queryable;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/adapters/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/adapters/postgres.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,CAO3D"}

package/dist/adapters/postgres.js

@@ -0,0 +1,35 @@
+/**
+ * postgres.js adapter for Melange.
+ *
+ * This module provides an adapter to use postgres.js with the Melange Checker.
+ */
+/**
+ * postgresAdapter wraps a postgres.js Sql instance for use with Checker.
+ *
+ * @param sql - A postgres.js Sql instance
+ * @returns A Queryable instance
+ *
+ * @example
+ * ```typescript
+ * import postgres from 'postgres';
+ * import { Checker, postgresAdapter } from '@pthm/melange';
+ *
+ * const sql = postgres(process.env.DATABASE_URL);
+ * const checker = new Checker(postgresAdapter(sql));
+ *
+ * const decision = await checker.check(
+ *   { type: 'user', id: '123' },
+ *   'can_read',
+ *   { type: 'repository', id: '456' }
+ * );
+ * ```
+ */
+export function postgresAdapter(sql) {
+    return {
+        async query(text, params = []) {
+            const rows = await sql.unsafe(text, params);
+            return { rows };
+        },
+    };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/adapters/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/adapters/postgres.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,GAAgB;IAC9C,OAAO;QACL,KAAK,CAAC,KAAK,CAAU,IAAY,EAAE,SAAgB,EAAE;YACnD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,MAAM,CAAI,IAAI,EAAE,MAAM,CAAC,CAAC;YAC/C,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cache.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Caching for Melange authorization checks.
+ *
+ * This module provides cache interfaces and implementations for storing
+ * permission check results to reduce database load.
+ */
+import type { Decision } from './types.js';
+/**
+ * Cache stores permission check results.
+ *
+ * Implementations should be safe for concurrent access if the Checker
+ * is shared across requests. For request-scoped caching, create a new
+ * Checker per request with a request-scoped cache.
+ */
+export interface Cache {
+    /**
+     * Get a cached decision.
+     *
+     * @param key - Cache key
+     * @returns Cached decision, or undefined if not found or expired
+     */
+    get(key: string): Promise<Decision | undefined>;
+    /**
+     * Store a decision in the cache.
+     *
+     * @param key - Cache key
+     * @param value - Decision to cache
+     */
+    set(key: string, value: Decision): Promise<void>;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * NoopCache is a no-op cache that never stores anything.
+ *
+ * This is the default cache implementation, suitable for applications
+ * that don't want caching overhead or have other caching strategies.
+ */
+export declare class NoopCache implements Cache {
+    get(_key: string): Promise<Decision | undefined>;
+    set(_key: string, _value: Decision): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * MemoryCache is a simple in-memory cache with TTL support.
+ *
+ * This cache stores decisions in a Map with time-based expiration.
+ * It's suitable for single-instance applications or request-scoped caching.
+ *
+ * For multi-instance deployments, consider using a distributed cache
+ * like Redis with a custom Cache implementation.
+ *
+ * @example
+ * ```typescript
+ * import { Checker, MemoryCache } from '@pthm/melange';
+ * import { Pool } from 'pg';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const cache = new MemoryCache(60000); // 60 second TTL
+ * const checker = new Checker(pool, { cache });
+ *
+ * // First check hits database
+ * await checker.check(user, 'can_read', repo);
+ *
+ * // Second check within 60s uses cache
+ * await checker.check(user, 'can_read', repo); // cached
+ * ```
+ */
+export declare class MemoryCache implements Cache {
+    private readonly cache;
+    private readonly ttlMs;
+    /**
+     * Create a new MemoryCache.
+     *
+     * @param ttlMs - Time to live in milliseconds (default: 60000 = 1 minute)
+     */
+    constructor(ttlMs?: number);
+    get(key: string): Promise<Decision | undefined>;
+    set(key: string, value: Decision): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Get the number of entries in the cache.
+     *
+     * Note: This includes expired entries that haven't been accessed yet.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,KAAK;IAC/B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAIhD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,WAAY,YAAW,KAAK;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;OAIG;gBACS,KAAK,GAAE,MAAc;IAO3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAe/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}