kern-db 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# kern-db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PostgreSQL database layer with ambient transactions, typed SQL queries, and test transactions.
+It is the database layer of [kern-orm](https://github.com/IlyaSemenov/kern-orm), and it works without the ORM.
+
+kern-db is in early development, and the API changes between minor versions.
+
+See [Getting Started](https://ilyasemenov.github.io/kern-orm/database/getting-started) in the documentation.
+
+## Install
+
+```sh
+npm install kern-db postgres
+```
+
+## Usage
+
+```ts
+import { createDatabase } from "kern-db"
+import { postgresJsDriver } from "kern-db/postgres-js"
+import * as t from "kern-db/types"
+import postgres from "postgres"
+
+const database = createDatabase({
+  driver: postgresJsDriver(postgres(process.env.DATABASE_URL!)),
+})
+
+// Queries in the callback, including in called functions, join the transaction.
+await database.transaction(async () => {
+  const id = await database.query`INSERT INTO form (name) VALUES (${"Survey"}) RETURNING id`.get(
+    t.uuid,
+  )
+  await database.query`UPDATE form SET published = true WHERE id = ${id}`
+})
+```

package/dist/array-BLt8ZNR5.mjs

@@ -0,0 +1,77 @@
+import { o as defineType } from "./bytea-DNZ_ftio.mjs";
+// src/type/builtins/array.ts
+/**
+* Creates a type of one-dimensional arrays of `element` values.
+*
+* A `NULL` element decodes to `null`; a nullable `element` type, such as `array(text.nullable())`, types such elements.
+* Elements are separated by commas, as in arrays of all built-in types; a custom type with another delimiter, such as `box`, is not supported.
+*/
+function array(element) {
+	const encodeElement = (value) => value === null ? null : element.encode(value);
+	return defineType({
+		sqlType: `${element.sqlType}[]`,
+		castType: `${element.castType}[]`
+	}).transform({
+		decode(text) {
+			const values = parseArray(text);
+			for (let index = 0; index < values.length; index++) {
+				const value = values[index];
+				values[index] = value === null ? null : element.decode(value);
+			}
+			return values;
+		},
+		encode: (values) => formatArray(values, encodeElement)
+	});
+}
+/** Parses a one-dimensional array literal, such as `{a,"b c",NULL}`, into the text representations of its elements. */
+function parseArray(text) {
+	const start = text.startsWith("[") ? text.indexOf("=") + 1 : 0;
+	if (text[start] !== "{" || !text.endsWith("}")) throw new Error(`Unsupported array value "${text}"`);
+	const elements = [];
+	const end = text.length - 1;
+	if (start + 1 === end) return elements;
+	let index = start + 1;
+	while (true) {
+		if (text[index] === "{") throw new Error("Multidimensional arrays are not supported");
+		if (text[index] === "\"") {
+			let element = "";
+			index++;
+			while (index < end && text[index] !== "\"") {
+				if (text[index] === "\\") {
+					index++;
+					if (index === end) break;
+				}
+				element += text[index];
+				index++;
+			}
+			if (index === end) throw new Error(`Unterminated quoted element in array value "${text}"`);
+			elements.push(element);
+			index++;
+		} else {
+			let next = text.indexOf(",", index);
+			if (next === -1) next = end;
+			if (next === index) throw new Error(`Malformed array value "${text}"`);
+			const element = text.slice(index, next);
+			elements.push(element === "NULL" ? null : element);
+			index = next;
+		}
+		if (index === end) return elements;
+		if (text[index] !== ",") throw new Error(`Malformed array value "${text}"`);
+		index++;
+	}
+}
+/**
+* Formats `values` as an array literal, such as `{"a","b c",NULL}`, of the text representations that `encodeElement` returns.
+*
+* It quotes every element other than `NULL`, so that it needs no scan for the characters that PostgreSQL requires to quote.
+*/
+function formatArray(values, encodeElement) {
+	let text = "{";
+	for (let index = 0; index < values.length; index++) text += `${index === 0 ? "" : ","}${formatArrayElement(encodeElement(values[index]))}`;
+	return `${text}}`;
+}
+/** Formats the text representation of an array element, quoting it unless it is `NULL`. */
+function formatArrayElement(element) {
+	return element === null ? "NULL" : `"${element.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+export { formatArray as n, array as t };

package/dist/builder.d.mts

@@ -0,0 +1,4 @@
+import { B as toMissingResult, D as encodeParameter, E as bindParameter, I as createFieldDecodeError, L as createResultDecodeError, N as ResultMode, R as isRecordKey, S as renderFragment, T as assertUntypedValue, V as toValueRows, _ as ParameterBinder, a as SqlQuery, c as StatementSource, l as startSqlQuery, v as SqlFragment, z as takeOnlyRow } from "./query-B8QCiInv.mjs";
+/** Quotes `name` as a PostgreSQL identifier, which keeps its case and any characters in it. */
+export declare function quoteIdentifier(name: string): string;
+export { type ParameterBinder, type ResultMode, SqlFragment, SqlQuery, type StatementSource, assertUntypedValue, bindParameter, createFieldDecodeError, createResultDecodeError, encodeParameter, isRecordKey, renderFragment, startSqlQuery, takeOnlyRow, toMissingResult, toValueRows };

package/dist/builder.mjs

@@ -0,0 +1 @@
+export { d as SqlFragment, t as SqlQuery, v as assertUntypedValue, y as bindParameter, a as createFieldDecodeError, o as createResultDecodeError, b as encodeParameter, s as isRecordKey, x as quoteIdentifier, g as renderFragment, n as startSqlQuery, c as takeOnlyRow, l as toMissingResult, u as toValueRows } from "./query-g8iaj0Fx.mjs";

package/dist/bytea-DNZ_ftio.mjs

@@ -0,0 +1,92 @@
+// src/type/type.ts
+/** Runtime mark of types, which tells them apart from other objects with the same members. */
+const typeBrand = Symbol("kern-db.type");
+/**
+* Defines a type whose values are the PostgreSQL text representations as they are.
+*
+* `transform` converts them to other values, such as `number[]` for `vector`.
+*/
+function defineType(options) {
+	if (isType(options)) throw new TypeError("defineType() of kern-db takes options, not a type");
+	if (options.castType === void 0 && options.sqlType.includes("(")) throw new TypeError(`Define the type parameters of "${options.sqlType}" using withParameters(), or set castType`);
+	return createType({
+		sqlType: options.sqlType,
+		castType: options.castType ?? options.sqlType,
+		encode: keepText,
+		decode: keepText,
+		isNullable: false,
+		formatSqlType: void 0
+	});
+}
+/** Tells whether `value` is a type, including an object that copies the members of one. */
+function isType(value) {
+	return typeof value === "object" && value !== null && typeBrand in value;
+}
+function createType(state) {
+	const derive = (changes) => createType({
+		...state,
+		...changes
+	});
+	const { formatSqlType } = state;
+	const type = Object.freeze({
+		[typeBrand]: true,
+		sqlType: state.sqlType,
+		castType: state.castType,
+		isNullable: state.isNullable,
+		encode: state.encode,
+		decode: state.decode,
+		transform: ({ decode, encode }) => derive({
+			encode: encode ? (value) => state.encode(encode(value)) : state.encode,
+			decode: (text) => decode(state.decode(text))
+		}),
+		withParameters: (format) => derive({ formatSqlType: format }),
+		...formatSqlType && { with: (...parameters) => derive({ sqlType: formatSqlType(...parameters) }) },
+		nullable: () => derive({ isNullable: true }),
+		of: () => type
+	});
+	return type;
+}
+/** Encodes and decodes a value that is its PostgreSQL text representation. */
+function keepText(text) {
+	return text;
+}
+// src/type/builtins/boolean.ts
+/** `boolean` values. */
+const boolean = /* @__PURE__ */ defineType({ sqlType: "boolean" }).transform({
+	decode: decodeBoolean,
+	encode: encodeBoolean
+});
+/** Converts a Boolean value to its PostgreSQL text representation. */
+function encodeBoolean(value) {
+	return value ? "t" : "f";
+}
+/** Converts the PostgreSQL text representation of a Boolean value, `t` or `f`, to the value. */
+function decodeBoolean(text) {
+	return text === "t";
+}
+// src/type/builtins/bytea.ts
+/** Binary data; PostgreSQL represents it in hex, which requires the default `bytea_output` setting. */
+const bytea = /* @__PURE__ */ defineType({ sqlType: "bytea" }).transform({
+	decode: decodeBytea,
+	encode: encodeBytea
+});
+const hexDigits = "0123456789abcdef";
+/** Encodes bytes as a hex `bytea` literal, such as `\\x00ff`. */
+function encodeBytea(bytes) {
+	let text = "\\x";
+	for (const byte of bytes) text += hexDigits[byte >> 4] + hexDigits[byte & 15];
+	return text;
+}
+/** Decodes a hex `bytea` literal into bytes. */
+function decodeBytea(text) {
+	if (!text.startsWith("\\x")) throw new Error("Unsupported bytea value; kern-db expects bytea_output hex");
+	const bytes = new Uint8Array((text.length - 2) / 2);
+	for (let index = 0; index < bytes.length; index++) bytes[index] = readHexDigit(text, 2 + index * 2) << 4 | readHexDigit(text, 3 + index * 2);
+	return bytes;
+}
+/** Reads the hex digit at `index`, in either case. */
+function readHexDigit(text, index) {
+	const code = text.charCodeAt(index);
+	return code <= 57 ? code - 48 : (code | 32) - 87;
+}
+export { encodeBoolean as a, decodeBoolean as i, encodeBytea as n, defineType as o, boolean as r, isType as s, bytea as t };