@prisma-next/sql-contract 0.0.1 → 0.1.0-pr.32.1
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 +13 -4
- package/dist/exports/factories.d.ts +9 -1
- package/dist/exports/factories.js +3 -2
- package/dist/exports/factories.js.map +1 -1
- package/dist/exports/types.d.ts +2 -1
- package/dist/exports/validators.js +2 -1
- package/dist/exports/validators.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -13,6 +13,15 @@ This package provides TypeScript type definitions, Arktype validators, and facto
|
|
|
13
13
|
- **IR Factories**: Provides pure factory functions for constructing contract IR structures in tests and authoring
|
|
14
14
|
- **Shared Plane Access**: Enables both migration-plane and runtime-plane packages to import SQL contract types without violating plane boundaries
|
|
15
15
|
|
|
16
|
+
## StorageColumn Structure
|
|
17
|
+
|
|
18
|
+
Each `StorageColumn` in SQL contracts includes both:
|
|
19
|
+
- **`nativeType`** (required): Native database type identifier (e.g., `'int4'`, `'text'`, `'vector'`) - used for database structure verification and migration planning
|
|
20
|
+
- **`codecId`** (required): Codec identifier (e.g., `'pg/int4@1'`, `'pg/text@1'`, `'pg/vector@1'`) - used for query builders and runtime codecs
|
|
21
|
+
- **`nullable`** (required): Whether the column is nullable
|
|
22
|
+
|
|
23
|
+
Both `nativeType` and `codecId` are required to ensure contracts are consumable by both the application (via codec IDs) and the database (via native types). See `docs/briefs/Sql-Contract-Native-and-Codec-Types.md` for details.
|
|
24
|
+
|
|
16
25
|
## Package Contents
|
|
17
26
|
|
|
18
27
|
- **TypeScript Types**: Type definitions for `SqlContract`, `SqlStorage`, `StorageTable`, `ModelDefinition`, and related types
|
|
@@ -58,14 +67,14 @@ Use factory functions to construct contract IR structures in tests:
|
|
|
58
67
|
```typescript
|
|
59
68
|
import { col, table, storage, model, contract, pk, unique, index, fk } from '@prisma-next/sql-contract/exports/factories';
|
|
60
69
|
|
|
61
|
-
// Create a column
|
|
62
|
-
const idColumn = col('pg/int4@1', false);
|
|
70
|
+
// Create a column (nativeType, codecId, nullable)
|
|
71
|
+
const idColumn = col('int4', 'pg/int4@1', false);
|
|
63
72
|
|
|
64
73
|
// Create a table
|
|
65
74
|
const userTable = table(
|
|
66
75
|
{
|
|
67
|
-
id: col('pg/int4@1'),
|
|
68
|
-
email: col('pg/text@1'),
|
|
76
|
+
id: col('int4', 'pg/int4@1'),
|
|
77
|
+
email: col('text', 'pg/text@1'),
|
|
69
78
|
},
|
|
70
79
|
{
|
|
71
80
|
pk: pk('id'),
|
|
@@ -1,7 +1,15 @@
|
|
|
1
1
|
import { StorageColumn, SqlStorage, ModelDefinition, SqlMappings, SqlContract, ForeignKey, Index, ModelField, PrimaryKey, StorageTable, UniqueConstraint } from './types.js';
|
|
2
2
|
import '@prisma-next/contract/types';
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
/**
|
|
5
|
+
* Creates a StorageColumn with nativeType and codecId.
|
|
6
|
+
*
|
|
7
|
+
* @param nativeType - Native database type identifier (e.g., 'int4', 'text', 'vector')
|
|
8
|
+
* @param codecId - Codec identifier (e.g., 'pg/int4@1', 'pg/text@1')
|
|
9
|
+
* @param nullable - Whether the column is nullable (default: false)
|
|
10
|
+
* @returns StorageColumn with nativeType and codecId
|
|
11
|
+
*/
|
|
12
|
+
declare function col(nativeType: string, codecId: string, nullable?: boolean): StorageColumn;
|
|
5
13
|
declare function pk(...columns: readonly string[]): PrimaryKey;
|
|
6
14
|
declare function unique(...columns: readonly string[]): UniqueConstraint;
|
|
7
15
|
declare function index(...columns: readonly string[]): Index;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/factories.ts"],"sourcesContent":["import type {\n ForeignKey,\n ForeignKeyReferences,\n Index,\n ModelDefinition,\n ModelField,\n ModelStorage,\n PrimaryKey,\n SqlContract,\n SqlMappings,\n SqlStorage,\n StorageColumn,\n StorageTable,\n UniqueConstraint,\n} from './types';\n\nexport function col(
|
|
1
|
+
{"version":3,"sources":["../../src/factories.ts"],"sourcesContent":["import type {\n ForeignKey,\n ForeignKeyReferences,\n Index,\n ModelDefinition,\n ModelField,\n ModelStorage,\n PrimaryKey,\n SqlContract,\n SqlMappings,\n SqlStorage,\n StorageColumn,\n StorageTable,\n UniqueConstraint,\n} from './types';\n\n/**\n * Creates a StorageColumn with nativeType and codecId.\n *\n * @param nativeType - Native database type identifier (e.g., 'int4', 'text', 'vector')\n * @param codecId - Codec identifier (e.g., 'pg/int4@1', 'pg/text@1')\n * @param nullable - Whether the column is nullable (default: false)\n * @returns StorageColumn with nativeType and codecId\n */\nexport function col(nativeType: string, codecId: string, nullable = false): StorageColumn {\n return {\n nativeType,\n codecId,\n nullable,\n };\n}\n\nexport function pk(...columns: readonly string[]): PrimaryKey {\n return {\n columns,\n };\n}\n\nexport function unique(...columns: readonly string[]): UniqueConstraint {\n return {\n columns,\n };\n}\n\nexport function index(...columns: readonly string[]): Index {\n return {\n columns,\n };\n}\n\nexport function fk(\n columns: readonly string[],\n refTable: string,\n refColumns: readonly string[],\n name?: string,\n): ForeignKey {\n const references: ForeignKeyReferences = {\n table: refTable,\n columns: refColumns,\n };\n return {\n columns,\n references,\n ...(name !== undefined && { name }),\n };\n}\n\nexport function table(\n columns: Record<string, StorageColumn>,\n opts?: {\n pk?: PrimaryKey;\n uniques?: readonly UniqueConstraint[];\n indexes?: readonly Index[];\n fks?: readonly ForeignKey[];\n },\n): StorageTable {\n return {\n columns,\n ...(opts?.pk !== undefined && { primaryKey: opts.pk }),\n uniques: opts?.uniques ?? [],\n indexes: opts?.indexes ?? [],\n foreignKeys: opts?.fks ?? [],\n };\n}\n\nexport function model(\n table: string,\n fields: Record<string, ModelField>,\n relations: Record<string, unknown> = {},\n): ModelDefinition {\n const storage: ModelStorage = { table };\n return {\n storage,\n fields,\n relations,\n };\n}\n\nexport function storage(tables: Record<string, StorageTable>): SqlStorage {\n return { tables };\n}\n\nexport function contract(opts: {\n target: string;\n coreHash: string;\n storage: SqlStorage;\n models?: Record<string, ModelDefinition>;\n relations?: Record<string, unknown>;\n mappings?: Partial<SqlMappings>;\n schemaVersion?: '1';\n targetFamily?: 'sql';\n profileHash?: string;\n capabilities?: Record<string, Record<string, boolean>>;\n extensions?: Record<string, unknown>;\n meta?: Record<string, unknown>;\n sources?: Record<string, unknown>;\n}): SqlContract {\n return {\n schemaVersion: opts.schemaVersion ?? '1',\n target: opts.target,\n targetFamily: opts.targetFamily ?? 'sql',\n coreHash: opts.coreHash,\n storage: opts.storage,\n models: opts.models ?? {},\n relations: opts.relations ?? {},\n mappings: (opts.mappings ?? {}) as SqlMappings,\n ...(opts.profileHash !== undefined && { profileHash: opts.profileHash }),\n ...(opts.capabilities !== undefined && { capabilities: opts.capabilities }),\n ...(opts.extensions !== undefined && { extensions: opts.extensions }),\n ...(opts.meta !== undefined && { meta: opts.meta }),\n ...(opts.sources !== undefined && { sources: opts.sources as Record<string, unknown> }),\n } as SqlContract;\n}\n"],"mappings":";AAwBO,SAAS,IAAI,YAAoB,SAAiB,WAAW,OAAsB;AACxF,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,MAAM,SAAwC;AAC5D,SAAO;AAAA,IACL;AAAA,EACF;AACF;AAEO,SAAS,UAAU,SAA8C;AACtE,SAAO;AAAA,IACL;AAAA,EACF;AACF;AAEO,SAAS,SAAS,SAAmC;AAC1D,SAAO;AAAA,IACL;AAAA,EACF;AACF;AAEO,SAAS,GACd,SACA,UACA,YACA,MACY;AACZ,QAAM,aAAmC;AAAA,IACvC,OAAO;AAAA,IACP,SAAS;AAAA,EACX;AACA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,GAAI,SAAS,UAAa,EAAE,KAAK;AAAA,EACnC;AACF;AAEO,SAAS,MACd,SACA,MAMc;AACd,SAAO;AAAA,IACL;AAAA,IACA,GAAI,MAAM,OAAO,UAAa,EAAE,YAAY,KAAK,GAAG;AAAA,IACpD,SAAS,MAAM,WAAW,CAAC;AAAA,IAC3B,SAAS,MAAM,WAAW,CAAC;AAAA,IAC3B,aAAa,MAAM,OAAO,CAAC;AAAA,EAC7B;AACF;AAEO,SAAS,MACdA,QACA,QACA,YAAqC,CAAC,GACrB;AACjB,QAAMC,WAAwB,EAAE,OAAAD,OAAM;AACtC,SAAO;AAAA,IACL,SAAAC;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEO,SAAS,QAAQ,QAAkD;AACxE,SAAO,EAAE,OAAO;AAClB;AAEO,SAAS,SAAS,MAcT;AACd,SAAO;AAAA,IACL,eAAe,KAAK,iBAAiB;AAAA,IACrC,QAAQ,KAAK;AAAA,IACb,cAAc,KAAK,gBAAgB;AAAA,IACnC,UAAU,KAAK;AAAA,IACf,SAAS,KAAK;AAAA,IACd,QAAQ,KAAK,UAAU,CAAC;AAAA,IACxB,WAAW,KAAK,aAAa,CAAC;AAAA,IAC9B,UAAW,KAAK,YAAY,CAAC;AAAA,IAC7B,GAAI,KAAK,gBAAgB,UAAa,EAAE,aAAa,KAAK,YAAY;AAAA,IACtE,GAAI,KAAK,iBAAiB,UAAa,EAAE,cAAc,KAAK,aAAa;AAAA,IACzE,GAAI,KAAK,eAAe,UAAa,EAAE,YAAY,KAAK,WAAW;AAAA,IACnE,GAAI,KAAK,SAAS,UAAa,EAAE,MAAM,KAAK,KAAK;AAAA,IACjD,GAAI,KAAK,YAAY,UAAa,EAAE,SAAS,KAAK,QAAmC;AAAA,EACvF;AACF;","names":["table","storage"]}
|
package/dist/exports/types.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/validators.ts"],"sourcesContent":["import { type } from 'arktype';\nimport type {\n ForeignKey,\n ForeignKeyReferences,\n Index,\n ModelDefinition,\n ModelField,\n ModelStorage,\n PrimaryKey,\n SqlContract,\n SqlStorage,\n StorageColumn,\n StorageTable,\n UniqueConstraint,\n} from './types';\n\nconst StorageColumnSchema = type.declare<StorageColumn>().type({\n
|
|
1
|
+
{"version":3,"sources":["../../src/validators.ts"],"sourcesContent":["import { type } from 'arktype';\nimport type {\n ForeignKey,\n ForeignKeyReferences,\n Index,\n ModelDefinition,\n ModelField,\n ModelStorage,\n PrimaryKey,\n SqlContract,\n SqlStorage,\n StorageColumn,\n StorageTable,\n UniqueConstraint,\n} from './types';\n\nconst StorageColumnSchema = type.declare<StorageColumn>().type({\n nativeType: 'string',\n codecId: 'string',\n nullable: 'boolean',\n});\n\nconst PrimaryKeySchema = type.declare<PrimaryKey>().type({\n columns: type.string.array().readonly(),\n 'name?': 'string',\n});\n\nconst UniqueConstraintSchema = type.declare<UniqueConstraint>().type({\n columns: type.string.array().readonly(),\n 'name?': 'string',\n});\n\nconst IndexSchema = type.declare<Index>().type({\n columns: type.string.array().readonly(),\n 'name?': 'string',\n});\n\nconst ForeignKeyReferencesSchema = type.declare<ForeignKeyReferences>().type({\n table: 'string',\n columns: type.string.array().readonly(),\n});\n\nconst ForeignKeySchema = type.declare<ForeignKey>().type({\n columns: type.string.array().readonly(),\n references: ForeignKeyReferencesSchema,\n 'name?': 'string',\n});\n\nconst StorageTableSchema = type.declare<StorageTable>().type({\n columns: type({ '[string]': StorageColumnSchema }),\n 'primaryKey?': PrimaryKeySchema,\n uniques: UniqueConstraintSchema.array().readonly(),\n indexes: IndexSchema.array().readonly(),\n foreignKeys: ForeignKeySchema.array().readonly(),\n});\n\nconst StorageSchema = type.declare<SqlStorage>().type({\n tables: type({ '[string]': StorageTableSchema }),\n});\n\nconst ModelFieldSchema = type.declare<ModelField>().type({\n column: 'string',\n});\n\nconst ModelStorageSchema = type.declare<ModelStorage>().type({\n table: 'string',\n});\n\nconst ModelSchema = type.declare<ModelDefinition>().type({\n storage: ModelStorageSchema,\n fields: type({ '[string]': ModelFieldSchema }),\n relations: type({ '[string]': 'unknown' }),\n});\n\nconst SqlContractSchema = type({\n 'schemaVersion?': \"'1'\",\n target: 'string',\n targetFamily: \"'sql'\",\n coreHash: 'string',\n 'profileHash?': 'string',\n 'capabilities?': 'Record<string, Record<string, boolean>>',\n 'extensions?': 'Record<string, unknown>',\n 'meta?': 'Record<string, unknown>',\n 'sources?': 'Record<string, unknown>',\n models: type({ '[string]': ModelSchema }),\n storage: StorageSchema,\n});\n\n/**\n * Validates the structural shape of SqlStorage using Arktype.\n *\n * @param value - The storage value to validate\n * @returns The validated storage if structure is valid\n * @throws Error if the storage structure is invalid\n */\nexport function validateStorage(value: unknown): SqlStorage {\n const result = StorageSchema(value);\n if (result instanceof type.errors) {\n const messages = result.map((p: { message: string }) => p.message).join('; ');\n throw new Error(`Storage validation failed: ${messages}`);\n }\n return result;\n}\n\n/**\n * Validates the structural shape of ModelDefinition using Arktype.\n *\n * @param value - The model value to validate\n * @returns The validated model if structure is valid\n * @throws Error if the model structure is invalid\n */\nexport function validateModel(value: unknown): ModelDefinition {\n const result = ModelSchema(value);\n if (result instanceof type.errors) {\n const messages = result.map((p: { message: string }) => p.message).join('; ');\n throw new Error(`Model validation failed: ${messages}`);\n }\n return result;\n}\n\n/**\n * Validates the structural shape of a SqlContract using Arktype.\n *\n * **Responsibility: Validation Only**\n * This function validates that the contract has the correct structure and types.\n * It does NOT normalize the contract - normalization must happen in the contract builder.\n *\n * The contract passed to this function must already be normalized (all required fields present).\n * If normalization is needed, it should be done by the contract builder before calling this function.\n *\n * This ensures all required fields are present and have the correct types.\n *\n * @param value - The contract value to validate (typically from a JSON import)\n * @returns The validated contract if structure is valid\n * @throws Error if the contract structure is invalid\n */\nexport function validateSqlContract<T extends SqlContract<SqlStorage>>(value: unknown): T {\n // Check targetFamily first to provide a clear error message for unsupported target families\n const rawValue = value as { targetFamily?: string };\n if (rawValue.targetFamily !== undefined && rawValue.targetFamily !== 'sql') {\n throw new Error(`Unsupported target family: ${rawValue.targetFamily}`);\n }\n\n const contractResult = SqlContractSchema(value);\n\n if (contractResult instanceof type.errors) {\n const messages = contractResult.map((p: { message: string }) => p.message).join('; ');\n throw new Error(`Contract structural validation failed: ${messages}`);\n }\n\n // After validation, contractResult matches the schema and preserves the input structure\n // TypeScript needs an assertion here due to exactOptionalPropertyTypes differences\n // between Arktype's inferred type and the generic T, but runtime-wise they're compatible\n return contractResult as T;\n}\n"],"mappings":";AAAA,SAAS,YAAY;AAgBrB,IAAM,sBAAsB,KAAK,QAAuB,EAAE,KAAK;AAAA,EAC7D,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,UAAU;AACZ,CAAC;AAED,IAAM,mBAAmB,KAAK,QAAoB,EAAE,KAAK;AAAA,EACvD,SAAS,KAAK,OAAO,MAAM,EAAE,SAAS;AAAA,EACtC,SAAS;AACX,CAAC;AAED,IAAM,yBAAyB,KAAK,QAA0B,EAAE,KAAK;AAAA,EACnE,SAAS,KAAK,OAAO,MAAM,EAAE,SAAS;AAAA,EACtC,SAAS;AACX,CAAC;AAED,IAAM,cAAc,KAAK,QAAe,EAAE,KAAK;AAAA,EAC7C,SAAS,KAAK,OAAO,MAAM,EAAE,SAAS;AAAA,EACtC,SAAS;AACX,CAAC;AAED,IAAM,6BAA6B,KAAK,QAA8B,EAAE,KAAK;AAAA,EAC3E,OAAO;AAAA,EACP,SAAS,KAAK,OAAO,MAAM,EAAE,SAAS;AACxC,CAAC;AAED,IAAM,mBAAmB,KAAK,QAAoB,EAAE,KAAK;AAAA,EACvD,SAAS,KAAK,OAAO,MAAM,EAAE,SAAS;AAAA,EACtC,YAAY;AAAA,EACZ,SAAS;AACX,CAAC;AAED,IAAM,qBAAqB,KAAK,QAAsB,EAAE,KAAK;AAAA,EAC3D,SAAS,KAAK,EAAE,YAAY,oBAAoB,CAAC;AAAA,EACjD,eAAe;AAAA,EACf,SAAS,uBAAuB,MAAM,EAAE,SAAS;AAAA,EACjD,SAAS,YAAY,MAAM,EAAE,SAAS;AAAA,EACtC,aAAa,iBAAiB,MAAM,EAAE,SAAS;AACjD,CAAC;AAED,IAAM,gBAAgB,KAAK,QAAoB,EAAE,KAAK;AAAA,EACpD,QAAQ,KAAK,EAAE,YAAY,mBAAmB,CAAC;AACjD,CAAC;AAED,IAAM,mBAAmB,KAAK,QAAoB,EAAE,KAAK;AAAA,EACvD,QAAQ;AACV,CAAC;AAED,IAAM,qBAAqB,KAAK,QAAsB,EAAE,KAAK;AAAA,EAC3D,OAAO;AACT,CAAC;AAED,IAAM,cAAc,KAAK,QAAyB,EAAE,KAAK;AAAA,EACvD,SAAS;AAAA,EACT,QAAQ,KAAK,EAAE,YAAY,iBAAiB,CAAC;AAAA,EAC7C,WAAW,KAAK,EAAE,YAAY,UAAU,CAAC;AAC3C,CAAC;AAED,IAAM,oBAAoB,KAAK;AAAA,EAC7B,kBAAkB;AAAA,EAClB,QAAQ;AAAA,EACR,cAAc;AAAA,EACd,UAAU;AAAA,EACV,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,eAAe;AAAA,EACf,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,QAAQ,KAAK,EAAE,YAAY,YAAY,CAAC;AAAA,EACxC,SAAS;AACX,CAAC;AASM,SAAS,gBAAgB,OAA4B;AAC1D,QAAM,SAAS,cAAc,KAAK;AAClC,MAAI,kBAAkB,KAAK,QAAQ;AACjC,UAAM,WAAW,OAAO,IAAI,CAAC,MAA2B,EAAE,OAAO,EAAE,KAAK,IAAI;AAC5E,UAAM,IAAI,MAAM,8BAA8B,QAAQ,EAAE;AAAA,EAC1D;AACA,SAAO;AACT;AASO,SAAS,cAAc,OAAiC;AAC7D,QAAM,SAAS,YAAY,KAAK;AAChC,MAAI,kBAAkB,KAAK,QAAQ;AACjC,UAAM,WAAW,OAAO,IAAI,CAAC,MAA2B,EAAE,OAAO,EAAE,KAAK,IAAI;AAC5E,UAAM,IAAI,MAAM,4BAA4B,QAAQ,EAAE;AAAA,EACxD;AACA,SAAO;AACT;AAkBO,SAAS,oBAAuD,OAAmB;AAExF,QAAM,WAAW;AACjB,MAAI,SAAS,iBAAiB,UAAa,SAAS,iBAAiB,OAAO;AAC1E,UAAM,IAAI,MAAM,8BAA8B,SAAS,YAAY,EAAE;AAAA,EACvE;AAEA,QAAM,iBAAiB,kBAAkB,KAAK;AAE9C,MAAI,0BAA0B,KAAK,QAAQ;AACzC,UAAM,WAAW,eAAe,IAAI,CAAC,MAA2B,EAAE,OAAO,EAAE,KAAK,IAAI;AACpF,UAAM,IAAI,MAAM,0CAA0C,QAAQ,EAAE;AAAA,EACtE;AAKA,SAAO;AACT;","names":[]}
|
package/package.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@prisma-next/sql-contract",
|
|
3
|
-
"version": "0.0.1",
|
|
3
|
+
"version": "0.1.0-pr.32.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"description": "SQL contract types, validators, and IR factories for Prisma Next",
|
|
7
7
|
"dependencies": {
|
|
8
8
|
"arktype": "^2.1.25",
|
|
9
|
-
"@prisma-next/contract": "0.0.1"
|
|
9
|
+
"@prisma-next/contract": "0.1.0-pr.32.1"
|
|
10
10
|
},
|
|
11
11
|
"devDependencies": {
|
|
12
12
|
"@vitest/coverage-v8": "^2.1.1",
|