@tstdl/base 0.93.8 → 0.93.10

package/orm/sqls.js

@@ -4,7 +4,7 @@
  * simplifying common SQL operations like generating UUIDs, working with intervals,
  * and aggregating data.
  */
-import { isNumber } from '../utils/type-guards.js';
+import { isDefined, isNumber, isString } from '../utils/type-guards.js';
 import { sql, Table } from 'drizzle-orm';
 /** Drizzle SQL helper for getting the current transaction's timestamp. Returns a Date object. */
 export const TRANSACTION_TIMESTAMP = sql `transaction_timestamp()`;
@@ -14,7 +14,7 @@ export function autoAlias(column) {
     return sql `${column}`.as(`${column.table[Table['Symbol']['Name']]}_${column.name}`);
 }
 /**
- * Creates a Drizzle SQL interval expression.
+ * Creates a PostgreSQL interval expression.
  * @param value - The numeric value of the interval.
  * @param unit - The unit of the interval (e.g., 'day', 'hour').
  * @returns A Drizzle SQL object representing the interval.
@@ -23,7 +23,7 @@ export function interval(value, unit) {
     return sql `(${value} ||' ${sql.raw(unit)}')::interval`;
 }
 /**
- * Creates a Drizzle SQL `array_agg` aggregate function call.
+ * Creates a PostgreSQL `array_agg` aggregate function call.
  * Aggregates values from a column into a PostgreSQL array.
  * @template T - The Drizzle column type.
  * @param column - The column to aggregate.
@@ -33,7 +33,7 @@ export function arrayAgg(column) {
     return sql `array_agg(${column})`;
 }
 /**
- * Creates a Drizzle SQL `json_agg` aggregate function call.
+ * Creates a PostgreSQL `json_agg` aggregate function call.
  * Aggregates rows or column values into a JSON array.
  * @template T - The Drizzle table or column type.
  * @param tableOrColumn - The table or column to aggregate into JSON.
@@ -50,7 +50,7 @@ export function jsonAgg(tableOrColumn) {
  */
 jsonAgg.withNull = jsonAgg;
 /**
- * Creates a Drizzle SQL `coalesce` function call.
+ * Creates a PostgreSQL `coalesce` function call.
  * Returns the first non-null value from the provided list of columns or SQL expressions.
  * @template T - An array type of Drizzle Columns or SQL expressions.
  * @param columns - The columns or SQL expressions to check.
@@ -60,7 +60,7 @@ export function coalesce(...columns) {
     return sql `coalesce(${sql.join(columns, sql.raw(', '))})`;
 }
 /**
- * Creates a Drizzle SQL `to_jsonb` function call.
+ * Creates a PostgreSQL `to_jsonb` function call.
  * Converts the input column or SQL expression to a JSONB value.
  * @template T - The Drizzle column or SQL expression type.
  * @param column - The column or SQL expression to convert.
@@ -70,7 +70,7 @@ export function toJsonb(column) {
     return sql `to_jsonb(${column})`;
 }
 /**
- * Creates a Drizzle SQL `num_nulls` function call.
+ * Creates a PostgreSQL `num_nulls` function call.
  * Counts the number of null arguments.
  * @param columns - The columns to check for nulls.
  * @returns A Drizzle SQL object representing the count of nulls.
@@ -79,7 +79,7 @@ export function numNulls(...columns) {
     return sql `num_nulls(${sql.join(columns, sql.raw(', '))})`;
 }
 /**
- * Creates a Drizzle SQL `num_nonnulls` function call.
+ * Creates a PostgreSQL `num_nonnulls` function call.
  * Counts the number of non-null arguments.
  * @param columns - The columns to check for non-nulls.
  * @returns A Drizzle SQL object representing the count of non-nulls.
@@ -95,3 +95,138 @@ export function greatest(...values) {
     const sqlValues = values.map((value) => isNumber(value) ? sql.raw(String(value)) : value);
     return sql `greatest(${sql.join(sqlValues, sql.raw(', '))})`;
 }
+function getLanguageSql(language) {
+    return isString(language) ? sql `'${sql.raw(language)}'` : sql `${language}`;
+}
+export function toTsVector(language, column) {
+    return sql `to_tsvector(${getLanguageSql(language)}, ${column})`;
+}
+/**
+ * Creates a PostgreSQL `to_tsquery` function call.
+ * This function parses text into a tsquery, respecting operators like & (AND), | (OR), and ! (NOT).
+ * @param language The text search configuration (e.g., 'english').
+ * @param text The search query text with operators.
+ * @returns A Drizzle SQL object representing the tsquery.
+ */
+export function toTsQuery(language, text) {
+    return sql `to_tsquery(${getLanguageSql(language)}, ${text})`;
+}
+/**
+ * Creates a PostgreSQL `plainto_tsquery` function call.
+ * This function parses text into tokens and normalizes them, creating a tsquery
+ * where tokens are joined by the AND operator. It's useful for raw user input.
+ * @param language The text search configuration (e.g., 'english').
+ * @param text The search query text.
+ * @returns A Drizzle SQL object representing the tsquery.
+ */
+export function plainToTsQuery(language, text) {
+    return sql `plainto_tsquery(${getLanguageSql(language)}, ${text})`;
+}
+/**
+ * Creates a PostgreSQL `phraseto_tsquery` function call.
+ * This function is similar to `plainto_tsquery` but creates a tsquery that searches for a phrase.
+ * @param language The text search configuration (e.g., 'english').
+ * @param text The phrase to search for.
+ * @returns A Drizzle SQL object representing the tsquery.
+ */
+export function phraseToTsQuery(language, text) {
+    return sql `phraseto_tsquery(${getLanguageSql(language)}, ${text})`;
+}
+/**
+ * Creates a PostgreSQL `websearch_to_tsquery` function call.
+ * This function is similar to `plainto_tsquery` but also handles "quoted phrases"
+ * and prefixes terms with `-` or `!` for negation. It's suitable for web search style inputs.
+ * @param language The text search configuration (e.g., 'english').
+ * @param text The search query text.
+ * @returns A Drizzle SQL object representing the tsquery.
+ */
+export function websearchToTsQuery(language, text) {
+    return sql `websearch_to_tsquery(${getLanguageSql(language)}, ${text})`;
+}
+/**
+ * Creates a PostgreSQL `setweight` function call.
+ * Assigns a weight ('A', 'B', 'C', 'D') to a tsvector.
+ * @param tsvector The tsvector to weight.
+ * @param weight The weight to assign.
+ * @returns A Drizzle SQL object representing the weighted tsvector.
+ */
+export function setweight(tsvector, weight) {
+    return sql `setweight(${tsvector}, '${sql.raw(weight)}')`;
+}
+/**
+ * Creates a PostgreSQL `ts_rank_cd` function call for relevance ranking.
+ * @param tsvector The document's tsvector.
+ * @param tsquery The search query's tsquery.
+ * @param options Optional configuration for ranking, including weights and normalization.
+ * @returns A Drizzle SQL object representing the relevance score.
+ */
+export function tsRankCd(tsvector, tsquery, options) {
+    const parameters = [];
+    if (isDefined(options?.weights)) {
+        const weightParts = options.weights.map((w) => sql.raw(String(w)));
+        parameters.push(sql `ARRAY[${sql.join(weightParts, sql.raw(', '))}]::real[]`);
+    }
+    parameters.push(tsvector, tsquery);
+    if (isDefined(options?.normalization)) {
+        parameters.push(sql `${options.normalization}`);
+    }
+    return sql `ts_rank_cd(${sql.join(parameters, sql.raw(', '))})`;
+}
+/**
+ * Creates a PostgreSQL `ts_headline` function call for highlighting search results.
+ *
+ * @param language The text search configuration.
+ * @param document The original text column.
+ * @param tsquery The search query's tsquery.
+ * @param options Optional configuration object for ts_headline (e.g., { MaxWords: 10 }).
+ * @returns A Drizzle SQL object representing the highlighted text snippet.
+ *
+ * @warning If using HTML tags for `startSel` and `stopSel` (the default), be aware of
+ * Cross-Site Scripting (XSS) vulnerabilities. Ensure the `document` content is
+ * properly sanitized before rendering it in a browser if it comes from an untrusted source.
+ */
+export function tsHeadline(language, document, tsquery, options) {
+    const documentSql = isString(document) ? sql `${document}` : document;
+    if (isDefined(options)) {
+        const optionsString = Object.entries(options).map(([key, value]) => `${key[0].toUpperCase()}${key.slice(1)}=${String(value)}`).join(', ');
+        return sql `ts_headline(${getLanguageSql(language)}, ${documentSql}, ${tsquery}, '${sql.raw(optionsString)}')`;
+    }
+    return sql `ts_headline(${getLanguageSql(language)}, ${documentSql}, ${tsquery})`;
+}
+/**
+ * Creates a PostgreSQL `similarity` function call (from pg_trgm extension).
+ * Calculates the similarity between two strings based on trigram matching.
+ * @param left The first text column or expression.
+ * @param right The second text value or expression to compare against.
+ * @returns A Drizzle SQL object representing the similarity score (0 to 1).
+ */
+export function similarity(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `similarity(${leftSql}, ${rightSql})`;
+}
+/**
+ * Creates a PostgreSQL `%` operator call (from pg_trgm extension) for similarity check.
+ * Returns true if the similarity between the two arguments is greater than the current similarity threshold.
+ * @param left The text column or expression.
+ * @param right The text value or expression to compare against.
+ * @returns A Drizzle SQL object representing a boolean similarity check.
+ */
+export function isSimilar(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `(${leftSql}) % (${rightSql})`;
+}
+/**
+ * Creates a PostgreSQL `<->` operator call (from pg_trgm extension) for similarity distance.
+ * Returns the "distance" between the arguments, that is one minus the similarity() value.
+ * This is useful for ordering by similarity with an index.
+ * @param left The text column or expression.
+ * @param right The text value or expression to compare against.
+ * @returns A Drizzle SQL object representing the similarity distance.
+ */
+export function similarityDistance(left, right) {
+    const leftSql = isString(left) ? sql `${left}` : left;
+    const rightSql = isString(right) ? sql `${right}` : right;
+    return sql `(${leftSql}) <-> (${rightSql})`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.8",
+  "version": "0.93.10",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -18,7 +18,7 @@
     "pub": "npm run build:production && npm run cleanup:dist && npm publish dist/",
     "tsc:watch": "tsc --watch",
     "tsc-alias:watch": "tsc-alias --watch",
-    "cleanup:dist": "rm -vf dist/test* && rm -vrf dist/tools/",
+    "cleanup:dist": "rm -vrf dist/tools/",
     "generate:migration": "./scripts/manage-orm.sh generate",
     "generate:readmes": "deno run --allow-run=code2prompt --allow-read --allow-write=source --allow-net=generativelanguage.googleapis.com --allow-env=GEMINI_API_KEY generate-readmes.ts",
     "generate:readmes:new-only": "npm run generate:readmes -- --skip-existing",
@@ -136,7 +136,7 @@
   },
   "peerDependencies": {
     "@google-cloud/storage": "^7.17",
-    "@google/genai": "^1.24",
+    "@google/genai": "^1.25",
     "@tstdl/angular": "^0.93",
     "@zxcvbn-ts/core": "^3.0",
     "@zxcvbn-ts/language-common": "^3.0",

package/schema/schemas/object.js

@@ -167,7 +167,7 @@ function getObjectSchemaPropertiesFromReflection(metadata, type) {
     const properties = {};
     for (const [key, propertyMetadata] of metadata.properties) {
         const reflectionData = propertyMetadata.data.tryGet('schema');
-        const propertySchema = schemaReflectionDataToSchema(reflectionData, type, { type, key });
+        const propertySchema = schemaReflectionDataToSchema(reflectionData, propertyMetadata.type, { type, key });
         properties[key] = propertySchema;
     }
     for (const [key] of metadata.methods) {

package/test/drizzle/0000_sudden_sphinx.sql

@@ -0,0 +1,9 @@
+CREATE TABLE "test"."test" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"title" text NOT NULL,
+	"content" text NOT NULL,
+	"tags" text NOT NULL,
+	"language" text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "test_title_content_tags_idx" ON "test"."test" USING gin ((setweight(to_tsvector('simple', "title"), 'A') || setweight(to_tsvector('simple', "content"), 'B') || setweight(to_tsvector('simple', "tags"), 'C')));

package/test/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,79 @@
+{
+  "id": "5c221821-4273-489d-b533-2f49653ab8d1",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "test.test": {
+      "name": "test",
+      "schema": "test",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tags": {
+          "name": "tags",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "language": {
+          "name": "language",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "test_title_content_tags_idx": {
+          "name": "test_title_content_tags_idx",
+          "columns": [
+            {
+              "expression": "(setweight(to_tsvector(\"language\"::regconfig, \"title\"), 'A') || setweight(to_tsvector(\"language\"::regconfig, \"content\"), 'B') || setweight(to_tsvector(\"language\"::regconfig, \"tags\"), 'C'))",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "gin",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/test/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1760697525756,
+      "tag": "0000_sudden_sphinx",
+      "breakpoints": true
+    }
+  ]
+}

package/test/drizzle.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("drizzle-kit").Config;
+export default _default;

package/test/drizzle.config.js

@@ -0,0 +1,11 @@
+import { relative, resolve } from 'node:path';
+import { defineConfig } from 'drizzle-kit';
+export default defineConfig({
+    dialect: 'postgresql',
+    out: relative('./', resolve(__dirname, './drizzle/').replace('dist', 'source')),
+    schema: resolve(__dirname, './schemas.js'),
+    migrations: {
+        schema: 'test',
+        table: '_migrations',
+    },
+});

package/test/index.d.ts

@@ -0,0 +1,3 @@
+export * from './module.js';
+export * from './schemas.js';
+export * from './test.model.js';

package/test/index.js

@@ -0,0 +1,3 @@
+export * from './module.js';
+export * from './schemas.js';
+export * from './test.model.js';

package/test/module.d.ts

@@ -0,0 +1,6 @@
+import { type DatabaseConfig } from '../orm/server/index.js';
+export declare class TestModuleConfig {
+    database?: DatabaseConfig;
+}
+export declare function configureTest(config: TestModuleConfig): void;
+export declare function migrateTestSchema(): Promise<void>;

package/test/module.js

@@ -0,0 +1,17 @@
+import { inject, Injector } from '../injector/index.js';
+import { Database, migrate } from '../orm/server/index.js';
+export class TestModuleConfig {
+    database;
+}
+export function configureTest(config) {
+    Injector.register(TestModuleConfig, { useValue: config });
+}
+export async function migrateTestSchema() {
+    const connection = inject(TestModuleConfig, undefined, { optional: true })?.database?.connection;
+    const database = inject(Database, connection);
+    await migrate(database, {
+        migrationsSchema: 'test',
+        migrationsTable: '_migrations',
+        migrationsFolder: import.meta.resolve('./drizzle').replace('file://', ''),
+    });
+}

package/test/schemas.d.ts

@@ -0,0 +1,3 @@
+import { Test } from './test.model.js';
+export declare const testSchema: import("../orm/server/index.js").DatabaseSchema<"test">;
+export declare const test: import("../orm/server/types.js").PgTableFromType<typeof Test, "test">;

package/test/schemas.js

@@ -0,0 +1,4 @@
+import { databaseSchema } from '../orm/server/index.js';
+import { Test } from './test.model.js';
+export const testSchema = databaseSchema('test');
+export const test = testSchema.getTable(Test);

package/test/test.model.d.ts

@@ -0,0 +1,8 @@
+import { EntityWithoutMetadata, type NewEntity } from '../orm/index.js';
+export declare class Test extends EntityWithoutMetadata {
+    title: string;
+    content: string;
+    tags: string;
+    language: string;
+}
+export declare const testData: NewEntity<Test>[];