pg-codegen 5.14.0 → 5.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,9 +12,113 @@
12
12
  <a href="https://www.npmjs.com/package/pg-codegen"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=postgres%2Fpg-codegen%2Fpackage.json"/></a>
13
13
  </p>
14
14
 
15
- Type-safe TypeScript from a live PostgreSQL schema: application and row types, runtime decoders, serializers, column metadata and enum unions — one tree-shakable module per table.
15
+ A Prisma-like, fully typed database client generated from your live PostgreSQL schema — plus the types, decoders and serializers it is built on.
16
16
 
17
- > A database row arrives as `unknown`. `pg-codegen` is what turns it into a value TypeScript can trust, without a hand-written `as string` in sight.
17
+ > No hand-written row mappers, no `row.created_at as string`, no column lists at the call site. Point it at a database and query.
18
+
19
+ ## 🚀 Quick start
20
+
21
+ ```bash
22
+ npm install pg-codegen
23
+ pg-codegen --schema app_public --out src/generated
24
+ ```
25
+
26
+ ```ts
27
+ import { Pool } from 'pg';
28
+ import { createAppPublicDb } from './generated/app_public/db';
29
+
30
+ const db = createAppPublicDb(new Pool());
31
+
32
+ // full row, decoded and camelCase — no select needed
33
+ const user = await db.users.findFirst({ where: { email: 'nadia@example.com' } });
34
+
35
+ // narrow it inline; the result type follows
36
+ const names = await db.users.findMany({
37
+ where: { isActive: true, createdAt: { greaterThan: since } },
38
+ select: { id: true, username: true },
39
+ orderBy: { createdAt: 'DESC' },
40
+ limit: 20
41
+ });
42
+
43
+ const created = await db.users.create({ data: { username: 'nadia', email: 'nadia@example.com' } });
44
+ await db.users.updateOrThrow({ where: { id: created.id }, data: { isActive: false } });
45
+ ```
46
+
47
+ Connection settings come from the standard PG environment (`PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`) via `pg-env`.
48
+
49
+ ## 🧭 The client
50
+
51
+ One `create<Schema>Db(db, options?)` factory per schema, one client per table:
52
+
53
+ | Method | Returns |
54
+ |---|---|
55
+ | `findMany(args?)` | `SelectResult[]` |
56
+ | `findFirst(args?)` | `SelectResult \| null` |
57
+ | `findFirstOrThrow(args?)` | `SelectResult`, else `RowNotFoundError` |
58
+ | `count(where?)` | `number` |
59
+ | `create({ data, select? })` | the inserted row |
60
+ | `update({ where, data, select? })` | the updated rows |
61
+ | `updateOrThrow({ where, data, select? })` | one updated row, else `RowNotFoundError` |
62
+ | `delete({ where, select? })` | the deleted rows |
63
+ | `$with(db)` | the same clients bound to another connection |
64
+
65
+ `where` / `select` / `orderBy` are keyed by camelCase field names and mapped to physical columns for you. `where` speaks the same query-spec grammar as the GraphQL side — `equalTo`, `notEqualTo`, `in`, `notIn`, `lessThan`, `greaterThanOrEqualTo`, `like`, `likeInsensitive`, `startsWith`, `includes`, `isNull`, … — and a bare value means `equalTo` (`null` means `isNull`):
66
+
67
+ ```ts
68
+ await db.posts.findMany({ where: { authorId, status: { in: ['draft', 'review'] }, publishedAt: null } });
69
+ await db.posts.findMany({ where: { or: [{ authorId }, { editorId: authorId }], not: { status: 'archived' } } });
70
+ ```
71
+
72
+ `and` / `or` / `not` nest the same shape.
73
+
74
+ `update` and `delete` **require** a `where`: an empty filter throws rather than rewriting the table. Reads accept one and read the table unfiltered.
75
+
76
+ Writes are encoded from the generated column metadata (json/jsonb columns stringified, `Date` → ISO), and every returned row comes back through the generated per-column decoders, so a value that does not match its column's type raises `CoerceError` instead of flowing on as a lie.
77
+
78
+ ### Selections type the result
79
+
80
+ `select` is the only projection, stated either way round, and the return type follows it with nothing to annotate:
81
+
82
+ ```ts
83
+ await db.emailIdentities.findFirst({ where: { id } });
84
+ // EmailIdentities | null — every column
85
+
86
+ await db.emailIdentities.findFirst({ select: { id: true, slug: true } });
87
+ // Pick<EmailIdentities, 'id' | 'slug'> | null
88
+
89
+ await db.emailIdentities.findFirst({ select: { databaseId: false } });
90
+ // Omit<EmailIdentities, 'databaseId'> | null
91
+ ```
92
+
93
+ Excluding is what a caller reaches for when a field must not be carried — a secret's id, row bookkeeping — or when this binding's table genuinely lacks it: an excluded field is absent from the type, so reading it does not compile. Naming any field `true` is a projection and wins outright; the excluded ones are simply not in it.
94
+
95
+ ### Transactions
96
+
97
+ `$with` rebinds every table client to another connection, so a transaction is the same code against a different handle:
98
+
99
+ ```ts
100
+ const client = await pool.connect();
101
+ try {
102
+ await client.query('BEGIN');
103
+ const tx = db.$with(client);
104
+ const run = await tx.agentRuns.create({ data: { threadId, status: 'running' } });
105
+ await tx.agentEvents.create({ data: { runId: run.id, seq: 1 } });
106
+ await client.query('COMMIT');
107
+ } finally {
108
+ client.release();
109
+ }
110
+ ```
111
+
112
+ ### Tables provisioned under a different name
113
+
114
+ The schema and physical table names are runtime arguments, so one generated client serves a per-tenant or per-scope deployment of the same tables:
115
+
116
+ ```ts
117
+ const routing = createRoutingPublicDb(pool, {
118
+ schema: tenant.schema,
119
+ tables: { emailIdentities: 'platform_email_identities' }
120
+ });
121
+ ```
18
122
 
19
123
  ## ✨ What it generates
20
124
 
@@ -24,25 +128,47 @@ For every table, view, materialized view and partitioned table in the schemas yo
24
128
  |---|---|
25
129
  | `AgentRuns` | application shape, camelCase |
26
130
  | `AgentRunsRow` | database row shape, snake_case |
27
- | `AGENT_RUNS_TABLE` | `schema`, `name`, `qualifiedName`, `columns`, `primaryKey`, `columnByField` |
28
- | `AGENT_RUNS_FIELDS` | one decoder per column, for projections |
131
+ | `agentRunsTable` | `schema`, `name`, `qualifiedName`, `columns`, `primaryKey`, `columnByField` |
132
+ | `agentRunsFields` | one decoder per column, for projections |
29
133
  | `decodeAgentRuns` | decode an untrusted camelCase envelope (a wire payload, a parsed body) |
30
134
  | `decodeAgentRunsRow` | decode an untrusted database row |
31
135
  | `agentRunsFromRow` | row → application shape |
32
136
  | `decodeAgentRunsFromRow` | both, composed |
33
137
  | `serializeAgentRuns` | `Partial<AgentRuns>` → `Partial<AgentRunsRow>` for INSERT/UPDATE |
34
138
 
35
- Plus an `enums.ts` per schema: a literal union, a `readonly` value list and `as*`/`require*` checkers for every PostgreSQL enum a column references.
139
+ Plus, per schema, a `db.ts` (the client above), an `enums.ts` — a literal union, a `readonly` value list and `as*`/`require*` checkers for every PostgreSQL enum a column references — and barrels; and one shared `client.ts` runtime at the root.
36
140
 
37
141
  Every decoder is backed by [`@constructive-io/coerce`](../../packages/coerce): a NOT NULL column throws `CoerceError` naming the offending column, a nullable column answers `null`, and the text forms `pg` returns for `int8`/`numeric` are parsed rather than passed through as strings. Nothing is silently coerced across types, so a malformed row cannot become a default value.
38
142
 
39
- ## 🛠️ Install
143
+ ## 🔧 Below the client
40
144
 
41
- ```bash
42
- npm install pg-codegen
145
+ The client covers single-table reads and writes. For a join, a function call, or SQL the builder does not model, keep the query and decode its columns — `agentRunsFields` takes an overridable label so the error names the alias the query actually used:
146
+
147
+ ```ts
148
+ import { agentRunsFields } from '@my/db-types/codegen_test/agent-runs';
149
+ import { threadsFields } from '@my/db-types/codegen_test/threads';
150
+
151
+ const { rows } = await db.query(`
152
+ SELECT r.id, r.status, t.title AS thread_title
153
+ FROM agent_runs r JOIN threads t ON t.id = r.thread_id
154
+ `);
155
+
156
+ const summaries = rows.map(row => ({
157
+ id: agentRunsFields.id(row.id),
158
+ status: agentRunsFields.status(row.status),
159
+ threadTitle: threadsFields.title(row.thread_title, 'run_summary.thread_title')
160
+ }));
43
161
  ```
44
162
 
45
- ## 🚀 Usage
163
+ A whole row from a `SELECT *`-shaped query decodes in one call, and each table is its own module so a bundle carries only what it touches:
164
+
165
+ ```ts
166
+ import { decodeAgentRunsFromRow } from '@my/db-types/codegen_test/agent-runs';
167
+
168
+ const run = decodeAgentRunsFromRow(rows[0]); // AgentRuns, or CoerceError naming the column
169
+ ```
170
+
171
+ ## 📟 CLI
46
172
 
47
173
  ```bash
48
174
  pg-codegen --schema app_public --out src/generated
@@ -52,9 +178,9 @@ pg-codegen --schema app_public --out src/generated --check
52
178
 
53
179
  `--check` re-introspects and compares against the committed output, exiting non-zero on drift — run it in CI so generated types cannot go stale against a migration.
54
180
 
55
- Connection settings come from the standard PG environment (`PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`) via `pg-env`.
181
+ ## 🧩 Programmatic use
56
182
 
57
- Programmatically — for a schema whose physical name is per-tenant, say, where you want to rewrite it to a stable alias before emitting:
183
+ For a schema whose physical name is per-tenant, say, where you want to rewrite it to a stable alias before emitting:
58
184
 
59
185
  ```ts
60
186
  import { Client } from 'pg';
@@ -70,53 +196,6 @@ for (const schema of ir.schemas) {
70
196
  await writeFileTree(outDir, emitFileTree(ir));
71
197
  ```
72
198
 
73
- ## 📟 Example output
74
-
75
- ```ts
76
- // generated/codegen_test/agent-runs.ts
77
- export interface AgentRuns {
78
- id: string;
79
- threadId: string;
80
- status: RunStatus;
81
- tags: string[];
82
- retrySeconds: number[] | null;
83
- lastEventSeq: number;
84
- finishedAt: string | null;
85
- }
86
-
87
- export const decodeAgentRunsFromRow = (value: unknown, label = 'codegen_test.agent_runs'): AgentRuns =>
88
- agentRunsFromRow(decodeAgentRunsRow(value, label));
89
- ```
90
-
91
- Consume per table, so a bundle carries only the tables it touches:
92
-
93
- ```ts
94
- import { decodeAgentRunsFromRow } from '@my/db-types/codegen_test/agent-runs';
95
-
96
- const { rows } = await db.query('SELECT * FROM agent_runs WHERE id = $1', [id]);
97
- const run = decodeAgentRunsFromRow(rows[0]); // AgentRuns, or CoerceError naming the column
98
- ```
99
-
100
- ### Projections
101
-
102
- A joined or partial SELECT is not a whole row, so a record decoder would reject it. Decode it column by column instead — `FIELDS` takes an overridable label so the error names the alias the query actually used:
103
-
104
- ```ts
105
- import { AGENT_RUNS_FIELDS } from '@my/db-types/codegen_test/agent-runs';
106
- import { THREADS_FIELDS } from '@my/db-types/codegen_test/threads';
107
-
108
- const { rows } = await db.query(`
109
- SELECT r.id, r.status, t.title AS thread_title
110
- FROM agent_runs r JOIN threads t ON t.id = r.thread_id
111
- `);
112
-
113
- const summaries = rows.map(row => ({
114
- id: AGENT_RUNS_FIELDS.id(row.id),
115
- status: AGENT_RUNS_FIELDS.status(row.status),
116
- threadTitle: THREADS_FIELDS.title(row.thread_title, 'run_summary.thread_title')
117
- }));
118
- ```
119
-
120
199
  ## 🧱 How it works
121
200
 
122
201
  ```
@@ -125,7 +204,7 @@ PostgreSQL → introspectron → IR (ir.ts) → emitters (emit/*) → file tree
125
204
 
126
205
  `buildIr` normalizes an introspection result into the shape every emitter consumes: columns with a resolved scalar, nullability, defaults, primary keys, and the enums they reference. Domains are unwrapped to their base type, arrays carry their element scalar, and a type with no mapping degrades to `unknown` rather than to `any` — the generator never claims to know a shape it does not.
127
206
 
128
- Emission is Babel AST rather than string templates, so output is stable enough to snapshot and to diff in `--check`.
207
+ Emission is Babel AST rather than string templates, so output is stable enough to snapshot and to diff in `--check`. The client runtime is the one exception: `emit/templates/client.ts` is real, typechecked, tested source that is copied into the output, so the runtime every generated client shares is not assembled from AST.
129
208
 
130
209
  ---
131
210
 
package/cli.d.ts CHANGED
@@ -3,6 +3,8 @@ interface CliArgs {
3
3
  schemas: string[];
4
4
  out: string;
5
5
  check: boolean;
6
+ include: string[];
7
+ exclude: string[];
6
8
  }
7
9
  export declare const parseArgs: (argv: string[]) => CliArgs;
8
10
  export declare const main: (argv: string[]) => Promise<number>;
package/cli.js CHANGED
@@ -19,24 +19,35 @@ const USAGE = `Usage: pg-codegen --schema <name> [--schema <name> ...] --out <di
19
19
  Options:
20
20
  --schema <name> A schema to generate records for (repeatable, or comma-separated)
21
21
  --out <dir> Directory the generated files are written to (or compared against)
22
+ --table <glob> Only generate these tables (repeatable, or comma-separated)
23
+ --exclude <glob> Skip these tables (repeatable, or comma-separated)
22
24
  --check Compare against the files already in --out and exit non-zero on drift
23
25
  --help Show this message
24
26
 
25
27
  Connection settings come from the standard PG environment variables.`;
26
28
  const parseArgs = (argv) => {
27
29
  const schemas = [];
30
+ const include = [];
31
+ const exclude = [];
28
32
  let out = '';
29
33
  let check = false;
34
+ const values = (value, flag) => {
35
+ if (!value)
36
+ throw new Error(`${flag} requires a value`);
37
+ return value.split(',').map(name => name.trim()).filter(Boolean);
38
+ };
30
39
  for (let i = 0; i < argv.length; i++) {
31
40
  const arg = argv[i];
32
41
  switch (arg) {
33
- case '--schema': {
34
- const value = argv[++i];
35
- if (!value)
36
- throw new Error('--schema requires a value');
37
- schemas.push(...value.split(',').map(name => name.trim()).filter(Boolean));
42
+ case '--schema':
43
+ schemas.push(...values(argv[++i], '--schema'));
44
+ break;
45
+ case '--table':
46
+ include.push(...values(argv[++i], '--table'));
47
+ break;
48
+ case '--exclude':
49
+ exclude.push(...values(argv[++i], '--exclude'));
38
50
  break;
39
- }
40
51
  case '--out': {
41
52
  const value = argv[++i];
42
53
  if (!value)
@@ -60,7 +71,7 @@ const parseArgs = (argv) => {
60
71
  throw new Error('At least one --schema is required');
61
72
  if (!out)
62
73
  throw new Error('--out is required');
63
- return { schemas, out, check };
74
+ return { schemas, out, check, include, exclude };
64
75
  };
65
76
  exports.parseArgs = parseArgs;
66
77
  const main = async (argv) => {
@@ -84,7 +95,13 @@ const main = async (argv) => {
84
95
  });
85
96
  await client.connect();
86
97
  try {
87
- const files = await (0, generate_1.generate)(client, { schemas: args.schemas });
98
+ const files = await (0, generate_1.generate)(client, {
99
+ schemas: args.schemas,
100
+ tables: {
101
+ ...(args.include.length > 0 ? { include: args.include } : {}),
102
+ ...(args.exclude.length > 0 ? { exclude: args.exclude } : {})
103
+ }
104
+ });
88
105
  if (args.check) {
89
106
  const report = await (0, generate_1.checkFileTree)(args.out, files);
90
107
  if ((0, generate_1.isClean)(report)) {
package/emit/client.js CHANGED
@@ -74,10 +74,10 @@ const emitSchemaDbModule = (schema) => {
74
74
  ];
75
75
  for (const table of schema.tables) {
76
76
  const appType = (0, inflekt_1.toPascalCase)(table.name);
77
- const constant = (0, inflekt_1.toConstantCase)(table.name);
77
+ const model = (0, inflekt_1.toCamelCase)(table.name);
78
78
  const file = `./${(0, barrel_1.tableFileName)(table.name)}`;
79
79
  statements.push(typeImport([appType], file));
80
- statements.push((0, babel_1.namedImport)([`${constant}_FIELDS`, `${constant}_TABLE`], file));
80
+ statements.push((0, babel_1.namedImport)([`${model}Fields`, `${model}Table`], file));
81
81
  }
82
82
  const tableNameProps = schema.tables.map(table => {
83
83
  const prop = babel_1.t.tsPropertySignature(babel_1.t.identifier(modelKey(table)), babel_1.t.tsTypeAnnotation(babel_1.t.tsStringKeyword()));
@@ -97,12 +97,12 @@ const emitSchemaDbModule = (schema) => {
97
97
  dbMembers.push(withMember);
98
98
  statements.push(babel_1.t.exportNamedDeclaration(babel_1.t.tsInterfaceDeclaration(babel_1.t.identifier(dbTypeName), null, null, babel_1.t.tsInterfaceBody(dbMembers))));
99
99
  const clientProperties = schema.tables.map(table => {
100
- const constant = (0, inflekt_1.toConstantCase)(table.name);
100
+ const model = (0, inflekt_1.toCamelCase)(table.name);
101
101
  const spec = babel_1.t.objectExpression([
102
- babel_1.t.objectProperty(babel_1.t.identifier('schema'), babel_1.t.logicalExpression('??', babel_1.t.optionalMemberExpression(babel_1.t.identifier('options'), babel_1.t.identifier('schema'), false, true), babel_1.t.memberExpression(babel_1.t.identifier(`${constant}_TABLE`), babel_1.t.identifier('schema')))),
103
- babel_1.t.objectProperty(babel_1.t.identifier('table'), babel_1.t.logicalExpression('??', babel_1.t.optionalMemberExpression(babel_1.t.optionalMemberExpression(babel_1.t.identifier('options'), babel_1.t.identifier('tables'), false, true), babel_1.t.identifier(modelKey(table)), false, true), babel_1.t.memberExpression(babel_1.t.identifier(`${constant}_TABLE`), babel_1.t.identifier('name')))),
104
- babel_1.t.objectProperty(babel_1.t.identifier('columnByField'), babel_1.t.memberExpression(babel_1.t.identifier(`${constant}_TABLE`), babel_1.t.identifier('columnByField'))),
105
- babel_1.t.objectProperty(babel_1.t.identifier('fields'), babel_1.t.identifier(`${constant}_FIELDS`))
102
+ babel_1.t.objectProperty(babel_1.t.identifier('schema'), babel_1.t.logicalExpression('??', babel_1.t.optionalMemberExpression(babel_1.t.identifier('options'), babel_1.t.identifier('schema'), false, true), babel_1.t.memberExpression(babel_1.t.identifier(`${model}Table`), babel_1.t.identifier('schema')))),
103
+ babel_1.t.objectProperty(babel_1.t.identifier('table'), babel_1.t.logicalExpression('??', babel_1.t.optionalMemberExpression(babel_1.t.optionalMemberExpression(babel_1.t.identifier('options'), babel_1.t.identifier('tables'), false, true), babel_1.t.identifier(modelKey(table)), false, true), babel_1.t.memberExpression(babel_1.t.identifier(`${model}Table`), babel_1.t.identifier('name')))),
104
+ babel_1.t.objectProperty(babel_1.t.identifier('columnByField'), babel_1.t.memberExpression(babel_1.t.identifier(`${model}Table`), babel_1.t.identifier('columnByField'))),
105
+ babel_1.t.objectProperty(babel_1.t.identifier('fields'), babel_1.t.identifier(`${model}Fields`))
106
106
  ]);
107
107
  const jsonFields = table.columns.filter(column => column.scalar === 'json');
108
108
  if (jsonFields.length > 0) {
package/emit/record.js CHANGED
@@ -118,7 +118,7 @@ const decodeExpression = (column, value, label, usage) => {
118
118
  : babel_1.t.callExpression(babel_1.t.identifier(fnName), [value, label]);
119
119
  };
120
120
  /**
121
- * `<TABLE>_FIELDS`: one decoder per column, for rows that are NOT a whole
121
+ * `<table>Fields`: one decoder per column, for rows that are NOT a whole
122
122
  * table row — a joined projection, an aliased column, a partial SELECT — where
123
123
  * a record decoder would reject the absent columns.
124
124
  *
@@ -164,8 +164,8 @@ const emitRecordModule = (table) => {
164
164
  const usage = { coerceImports: new Set(), enumImports: new Set() };
165
165
  const pascal = (0, inflekt_1.toPascalCase)(table.name);
166
166
  const rowTypeName = `${pascal}Row`;
167
- const metadataName = `${(0, inflekt_1.toConstantCase)(table.name)}_TABLE`;
168
- const fieldsName = `${(0, inflekt_1.toConstantCase)(table.name)}_FIELDS`;
167
+ const metadataName = `${(0, inflekt_1.toCamelCase)(table.name)}Table`;
168
+ const fieldsName = `${(0, inflekt_1.toCamelCase)(table.name)}Fields`;
169
169
  const qualified = `${table.schema}.${table.name}`;
170
170
  const statements = [];
171
171
  // Application (camelCase) interface.
@@ -5,7 +5,7 @@ export interface Queryable {
5
5
  rowCount?: number | null;
6
6
  }>;
7
7
  }
8
- /** One generated decoder per field, as emitted in the `<TABLE>_FIELDS` constant. */
8
+ /** One generated decoder per field, as emitted in the `<table>Fields` constant. */
9
9
  export type FieldDecoders<App> = {
10
10
  [K in keyof App]: (value: unknown, label?: string) => App[K];
11
11
  };
@@ -18,7 +18,7 @@ export interface Queryable {
18
18
  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount?: number | null }>;
19
19
  }
20
20
 
21
- /** One generated decoder per field, as emitted in the `<TABLE>_FIELDS` constant. */
21
+ /** One generated decoder per field, as emitted in the `<table>Fields` constant. */
22
22
  export type FieldDecoders<App> = {
23
23
  [K in keyof App]: (value: unknown, label?: string) => App[K];
24
24
  };
package/esm/cli.js CHANGED
@@ -16,24 +16,35 @@ const USAGE = `Usage: pg-codegen --schema <name> [--schema <name> ...] --out <di
16
16
  Options:
17
17
  --schema <name> A schema to generate records for (repeatable, or comma-separated)
18
18
  --out <dir> Directory the generated files are written to (or compared against)
19
+ --table <glob> Only generate these tables (repeatable, or comma-separated)
20
+ --exclude <glob> Skip these tables (repeatable, or comma-separated)
19
21
  --check Compare against the files already in --out and exit non-zero on drift
20
22
  --help Show this message
21
23
 
22
24
  Connection settings come from the standard PG environment variables.`;
23
25
  export const parseArgs = (argv) => {
24
26
  const schemas = [];
27
+ const include = [];
28
+ const exclude = [];
25
29
  let out = '';
26
30
  let check = false;
31
+ const values = (value, flag) => {
32
+ if (!value)
33
+ throw new Error(`${flag} requires a value`);
34
+ return value.split(',').map(name => name.trim()).filter(Boolean);
35
+ };
27
36
  for (let i = 0; i < argv.length; i++) {
28
37
  const arg = argv[i];
29
38
  switch (arg) {
30
- case '--schema': {
31
- const value = argv[++i];
32
- if (!value)
33
- throw new Error('--schema requires a value');
34
- schemas.push(...value.split(',').map(name => name.trim()).filter(Boolean));
39
+ case '--schema':
40
+ schemas.push(...values(argv[++i], '--schema'));
41
+ break;
42
+ case '--table':
43
+ include.push(...values(argv[++i], '--table'));
44
+ break;
45
+ case '--exclude':
46
+ exclude.push(...values(argv[++i], '--exclude'));
35
47
  break;
36
- }
37
48
  case '--out': {
38
49
  const value = argv[++i];
39
50
  if (!value)
@@ -57,7 +68,7 @@ export const parseArgs = (argv) => {
57
68
  throw new Error('At least one --schema is required');
58
69
  if (!out)
59
70
  throw new Error('--out is required');
60
- return { schemas, out, check };
71
+ return { schemas, out, check, include, exclude };
61
72
  };
62
73
  export const main = async (argv) => {
63
74
  let args;
@@ -80,7 +91,13 @@ export const main = async (argv) => {
80
91
  });
81
92
  await client.connect();
82
93
  try {
83
- const files = await generate(client, { schemas: args.schemas });
94
+ const files = await generate(client, {
95
+ schemas: args.schemas,
96
+ tables: {
97
+ ...(args.include.length > 0 ? { include: args.include } : {}),
98
+ ...(args.exclude.length > 0 ? { exclude: args.exclude } : {})
99
+ }
100
+ });
84
101
  if (args.check) {
85
102
  const report = await checkFileTree(args.out, files);
86
103
  if (isClean(report)) {
@@ -4,7 +4,7 @@
4
4
  * TableClient per table over the generated metadata and field decoders.
5
5
  */
6
6
  import * as fs from 'fs';
7
- import { toCamelCase, toConstantCase, toPascalCase } from 'inflekt';
7
+ import { toCamelCase, toPascalCase } from 'inflekt';
8
8
  import * as path from 'path';
9
9
  import { exportConst, generateCode, namedImport, t, withJsDoc } from './babel';
10
10
  import { tableFileName } from './barrel';
@@ -37,10 +37,10 @@ export const emitSchemaDbModule = (schema) => {
37
37
  ];
38
38
  for (const table of schema.tables) {
39
39
  const appType = toPascalCase(table.name);
40
- const constant = toConstantCase(table.name);
40
+ const model = toCamelCase(table.name);
41
41
  const file = `./${tableFileName(table.name)}`;
42
42
  statements.push(typeImport([appType], file));
43
- statements.push(namedImport([`${constant}_FIELDS`, `${constant}_TABLE`], file));
43
+ statements.push(namedImport([`${model}Fields`, `${model}Table`], file));
44
44
  }
45
45
  const tableNameProps = schema.tables.map(table => {
46
46
  const prop = t.tsPropertySignature(t.identifier(modelKey(table)), t.tsTypeAnnotation(t.tsStringKeyword()));
@@ -60,12 +60,12 @@ export const emitSchemaDbModule = (schema) => {
60
60
  dbMembers.push(withMember);
61
61
  statements.push(t.exportNamedDeclaration(t.tsInterfaceDeclaration(t.identifier(dbTypeName), null, null, t.tsInterfaceBody(dbMembers))));
62
62
  const clientProperties = schema.tables.map(table => {
63
- const constant = toConstantCase(table.name);
63
+ const model = toCamelCase(table.name);
64
64
  const spec = t.objectExpression([
65
- t.objectProperty(t.identifier('schema'), t.logicalExpression('??', t.optionalMemberExpression(t.identifier('options'), t.identifier('schema'), false, true), t.memberExpression(t.identifier(`${constant}_TABLE`), t.identifier('schema')))),
66
- t.objectProperty(t.identifier('table'), t.logicalExpression('??', t.optionalMemberExpression(t.optionalMemberExpression(t.identifier('options'), t.identifier('tables'), false, true), t.identifier(modelKey(table)), false, true), t.memberExpression(t.identifier(`${constant}_TABLE`), t.identifier('name')))),
67
- t.objectProperty(t.identifier('columnByField'), t.memberExpression(t.identifier(`${constant}_TABLE`), t.identifier('columnByField'))),
68
- t.objectProperty(t.identifier('fields'), t.identifier(`${constant}_FIELDS`))
65
+ t.objectProperty(t.identifier('schema'), t.logicalExpression('??', t.optionalMemberExpression(t.identifier('options'), t.identifier('schema'), false, true), t.memberExpression(t.identifier(`${model}Table`), t.identifier('schema')))),
66
+ t.objectProperty(t.identifier('table'), t.logicalExpression('??', t.optionalMemberExpression(t.optionalMemberExpression(t.identifier('options'), t.identifier('tables'), false, true), t.identifier(modelKey(table)), false, true), t.memberExpression(t.identifier(`${model}Table`), t.identifier('name')))),
67
+ t.objectProperty(t.identifier('columnByField'), t.memberExpression(t.identifier(`${model}Table`), t.identifier('columnByField'))),
68
+ t.objectProperty(t.identifier('fields'), t.identifier(`${model}Fields`))
69
69
  ]);
70
70
  const jsonFields = table.columns.filter(column => column.scalar === 'json');
71
71
  if (jsonFields.length > 0) {
@@ -3,7 +3,7 @@
3
3
  * snake_case row interface, coerce-backed decoders for both, row/application
4
4
  * converters, a serializer for writes, and typed table metadata.
5
5
  */
6
- import { toCamelCase, toConstantCase, toPascalCase } from 'inflekt';
6
+ import { toCamelCase, toPascalCase } from 'inflekt';
7
7
  import { asConst, exportConst, generateCode, labelTemplate, namedImport, t, withJsDoc } from './babel';
8
8
  import { enumAsName, enumRequireName, enumTypeName } from './enums';
9
9
  const COERCERS = {
@@ -115,7 +115,7 @@ const decodeExpression = (column, value, label, usage) => {
115
115
  : t.callExpression(t.identifier(fnName), [value, label]);
116
116
  };
117
117
  /**
118
- * `<TABLE>_FIELDS`: one decoder per column, for rows that are NOT a whole
118
+ * `<table>Fields`: one decoder per column, for rows that are NOT a whole
119
119
  * table row — a joined projection, an aliased column, a partial SELECT — where
120
120
  * a record decoder would reject the absent columns.
121
121
  *
@@ -161,8 +161,8 @@ export const emitRecordModule = (table) => {
161
161
  const usage = { coerceImports: new Set(), enumImports: new Set() };
162
162
  const pascal = toPascalCase(table.name);
163
163
  const rowTypeName = `${pascal}Row`;
164
- const metadataName = `${toConstantCase(table.name)}_TABLE`;
165
- const fieldsName = `${toConstantCase(table.name)}_FIELDS`;
164
+ const metadataName = `${toCamelCase(table.name)}Table`;
165
+ const fieldsName = `${toCamelCase(table.name)}Fields`;
166
166
  const qualified = `${table.schema}.${table.name}`;
167
167
  const statements = [];
168
168
  // Application (camelCase) interface.
@@ -18,7 +18,7 @@ export interface Queryable {
18
18
  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount?: number | null }>;
19
19
  }
20
20
 
21
- /** One generated decoder per field, as emitted in the `<TABLE>_FIELDS` constant. */
21
+ /** One generated decoder per field, as emitted in the `<table>Fields` constant. */
22
22
  export type FieldDecoders<App> = {
23
23
  [K in keyof App]: (value: unknown, label?: string) => App[K];
24
24
  };
package/esm/generate.js CHANGED
@@ -28,9 +28,9 @@ export const emitFileTree = (ir) => {
28
28
  return files;
29
29
  };
30
30
  /** Introspect `schemas` through the given client and emit the file tree. */
31
- export const generate = async (client, { schemas }) => {
31
+ export const generate = async (client, { schemas, tables }) => {
32
32
  const introspection = await introspect(client, { schemas });
33
- const ir = buildIr(introspection, { schemas });
33
+ const ir = buildIr(introspection, { schemas, tables });
34
34
  return emitFileTree(ir);
35
35
  };
36
36
  /** Write an emitted file tree under `outDir`, creating directories as needed. */
package/esm/ir.js CHANGED
@@ -71,7 +71,26 @@ const resolveType = (type, typeById) => {
71
71
  const scalar = SCALAR_BY_TYPE_NAME[type.name];
72
72
  return { scalar: scalar ?? 'unknown', isArray: false };
73
73
  };
74
- export const buildIr = (introspection, { schemas }) => {
74
+ /** Matches a name against simple `*`/`?` glob patterns, as graphql/codegen does. */
75
+ const matchesPatterns = (name, patterns) => patterns.some(pattern => {
76
+ if (pattern.includes('*') || pattern.includes('?')) {
77
+ const expression = new RegExp(`^${pattern.replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
78
+ return expression.test(name);
79
+ }
80
+ return name === pattern;
81
+ });
82
+ export const buildIr = (introspection, { schemas, tables: tableFilter }) => {
83
+ const include = tableFilter?.include ?? ['*'];
84
+ const exclude = [...(tableFilter?.exclude ?? []), ...(tableFilter?.systemExclude ?? [])];
85
+ const isEmitted = (cls) => {
86
+ // A child partition is storage for its parent partitioned table, which is
87
+ // the relation callers read and write.
88
+ if (cls.isPartition === true)
89
+ return false;
90
+ if (!matchesPatterns(cls.name, include))
91
+ return false;
92
+ return exclude.length === 0 || !matchesPatterns(cls.name, exclude);
93
+ };
75
94
  const typeById = new Map(introspection.type.map(type => [type.id, type]));
76
95
  const namespaceNameById = new Map(introspection.namespace.map(namespace => [namespace.id, namespace.name]));
77
96
  const attributesByClassId = new Map();
@@ -103,7 +122,10 @@ export const buildIr = (introspection, { schemas }) => {
103
122
  return enumType.name;
104
123
  };
105
124
  const tables = introspection.class
106
- .filter((cls) => cls.namespaceName === schemaName && cls.classKind !== undefined && cls.classKind in TABLE_KINDS)
125
+ .filter((cls) => cls.namespaceName === schemaName &&
126
+ cls.classKind !== undefined &&
127
+ cls.classKind in TABLE_KINDS &&
128
+ isEmitted(cls))
107
129
  .map((cls) => {
108
130
  const attributes = (attributesByClassId.get(cls.id) ?? [])
109
131
  .filter(attribute => attribute.num > 0)
package/generate.d.ts CHANGED
@@ -1,12 +1,14 @@
1
1
  import { ClientBase } from 'pg';
2
- import { Ir } from './ir';
2
+ import { Ir, IrTableFilter } from './ir';
3
3
  /** Emit the full generated file tree (relative path -> content) from an IR. */
4
4
  export declare const emitFileTree: (ir: Ir) => Record<string, string>;
5
5
  export interface GenerateOptions {
6
6
  schemas: string[];
7
+ /** Which tables of those schemas to emit; child partitions are never emitted. */
8
+ tables?: IrTableFilter;
7
9
  }
8
10
  /** Introspect `schemas` through the given client and emit the file tree. */
9
- export declare const generate: (client: ClientBase, { schemas }: GenerateOptions) => Promise<Record<string, string>>;
11
+ export declare const generate: (client: ClientBase, { schemas, tables }: GenerateOptions) => Promise<Record<string, string>>;
10
12
  /** Write an emitted file tree under `outDir`, creating directories as needed. */
11
13
  export declare const writeFileTree: (outDir: string, files: Record<string, string>) => Promise<void>;
12
14
  export interface DriftReport {
package/generate.js CHANGED
@@ -35,9 +35,9 @@ const emitFileTree = (ir) => {
35
35
  };
36
36
  exports.emitFileTree = emitFileTree;
37
37
  /** Introspect `schemas` through the given client and emit the file tree. */
38
- const generate = async (client, { schemas }) => {
38
+ const generate = async (client, { schemas, tables }) => {
39
39
  const introspection = await (0, introspectron_1.introspect)(client, { schemas });
40
- const ir = (0, ir_1.buildIr)(introspection, { schemas });
40
+ const ir = (0, ir_1.buildIr)(introspection, { schemas, tables });
41
41
  return (0, exports.emitFileTree)(ir);
42
42
  };
43
43
  exports.generate = generate;
package/ir.d.ts CHANGED
@@ -40,8 +40,18 @@ export interface IrSchema {
40
40
  export interface Ir {
41
41
  schemas: IrSchema[];
42
42
  }
43
+ export interface IrTableFilter {
44
+ /** Table names to emit; glob patterns supported. Defaults to `['*']`. */
45
+ include?: string[];
46
+ /** Table names to skip; glob patterns supported. */
47
+ exclude?: string[];
48
+ /** Table names always skipped by a project convention; glob patterns supported. */
49
+ systemExclude?: string[];
50
+ }
43
51
  export interface BuildIrOptions {
44
52
  /** The schemas to include, in the order their modules should be emitted. */
45
53
  schemas: string[];
54
+ /** Which tables of those schemas to emit. */
55
+ tables?: IrTableFilter;
46
56
  }
47
- export declare const buildIr: (introspection: PgIntrospectionResultByKind, { schemas }: BuildIrOptions) => Ir;
57
+ export declare const buildIr: (introspection: PgIntrospectionResultByKind, { schemas, tables: tableFilter }: BuildIrOptions) => Ir;
package/ir.js CHANGED
@@ -74,7 +74,26 @@ const resolveType = (type, typeById) => {
74
74
  const scalar = SCALAR_BY_TYPE_NAME[type.name];
75
75
  return { scalar: scalar ?? 'unknown', isArray: false };
76
76
  };
77
- const buildIr = (introspection, { schemas }) => {
77
+ /** Matches a name against simple `*`/`?` glob patterns, as graphql/codegen does. */
78
+ const matchesPatterns = (name, patterns) => patterns.some(pattern => {
79
+ if (pattern.includes('*') || pattern.includes('?')) {
80
+ const expression = new RegExp(`^${pattern.replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
81
+ return expression.test(name);
82
+ }
83
+ return name === pattern;
84
+ });
85
+ const buildIr = (introspection, { schemas, tables: tableFilter }) => {
86
+ const include = tableFilter?.include ?? ['*'];
87
+ const exclude = [...(tableFilter?.exclude ?? []), ...(tableFilter?.systemExclude ?? [])];
88
+ const isEmitted = (cls) => {
89
+ // A child partition is storage for its parent partitioned table, which is
90
+ // the relation callers read and write.
91
+ if (cls.isPartition === true)
92
+ return false;
93
+ if (!matchesPatterns(cls.name, include))
94
+ return false;
95
+ return exclude.length === 0 || !matchesPatterns(cls.name, exclude);
96
+ };
78
97
  const typeById = new Map(introspection.type.map(type => [type.id, type]));
79
98
  const namespaceNameById = new Map(introspection.namespace.map(namespace => [namespace.id, namespace.name]));
80
99
  const attributesByClassId = new Map();
@@ -106,7 +125,10 @@ const buildIr = (introspection, { schemas }) => {
106
125
  return enumType.name;
107
126
  };
108
127
  const tables = introspection.class
109
- .filter((cls) => cls.namespaceName === schemaName && cls.classKind !== undefined && cls.classKind in TABLE_KINDS)
128
+ .filter((cls) => cls.namespaceName === schemaName &&
129
+ cls.classKind !== undefined &&
130
+ cls.classKind in TABLE_KINDS &&
131
+ isEmitted(cls))
110
132
  .map((cls) => {
111
133
  const attributes = (attributesByClassId.get(cls.id) ?? [])
112
134
  .filter(attribute => attribute.num > 0)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pg-codegen",
3
- "version": "5.14.0",
3
+ "version": "5.15.0",
4
4
  "author": "Constructive <developers@constructive.io>",
5
5
  "description": "Type-safe TypeScript codegen from live PostgreSQL schemas: row types, coerce-backed decoders, serializers, table metadata, and enum unions",
6
6
  "main": "index.js",
@@ -46,9 +46,9 @@
46
46
  "@babel/generator": "^7.29.1",
47
47
  "@babel/types": "^7.29.0",
48
48
  "@constructive-io/coerce": "^0.3.0",
49
- "@constructive-io/query-builder": "^3.10.4",
49
+ "@constructive-io/query-builder": "^3.10.5",
50
50
  "inflekt": "^0.8.1",
51
- "introspectron": "^5.12.0",
51
+ "introspectron": "^5.13.0",
52
52
  "pg": "^8.21.0",
53
53
  "pg-env": "^1.30.0"
54
54
  },
@@ -58,5 +58,5 @@
58
58
  "makage": "^0.3.0",
59
59
  "pgsql-test": "^5.11.0"
60
60
  },
61
- "gitHead": "4da763d15eefc04846e27a6e8b1647f57676be28"
61
+ "gitHead": "eca68e186b8785334076d487f7f736dbcd8af33e"
62
62
  }