@pgpm/utils 0.4.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Interweb, Inc.
+
+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/Makefile

@@ -0,0 +1,6 @@
+EXTENSION = launchql-utils
+DATA = sql/launchql-utils--0.4.6.sql
+
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)

package/README.md

@@ -0,0 +1,5 @@
+# @pgpm/utils
+
+General utility functions for PostgreSQL extensions.
+
+Provides common utility functions, helper procedures, and shared functionality used across LaunchQL extension modules.

package/__tests__/__snapshots__/utils.test.ts.snap

@@ -0,0 +1,9 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`bitmask less 1`] = `"01"`;
+
+exports[`bitmask more 1`] = `"00000000000000000101"`;
+
+exports[`less 1`] = `"01"`;
+
+exports[`more 1`] = `"00000000000000000101"`;

package/__tests__/utils.test.ts

@@ -0,0 +1,46 @@
+import { getConnections, PgTestClient } from 'pgsql-test';
+
+let pg: PgTestClient;
+let teardown:  () => Promise<void>;
+
+beforeAll(async () => {
+  ({ pg, teardown } = await getConnections());
+});
+
+afterAll(async () => {
+  await teardown();
+});
+
+it('more', async () => {
+  const { mask_pad } = await pg.one(
+    `SELECT utils.mask_pad($1, $2) AS mask_pad`,
+    ['101', 20]
+  );
+  expect(mask_pad).toMatchSnapshot();
+});
+
+it('less', async () => {
+  const { mask_pad } = await pg.one(
+    `SELECT utils.mask_pad($1, $2) AS mask_pad`,
+    ['101', 2]
+  );
+  expect(mask_pad).toMatchSnapshot();
+});
+
+describe('bitmask', () => {
+  it('more', async () => {
+    const { bitmask_pad } = await pg.one(
+      `SELECT utils.bitmask_pad($1::varbit, $2) AS bitmask_pad`,
+      ['101', 20]
+    );
+    expect(bitmask_pad).toMatchSnapshot();
+  });
+
+  it('less', async () => {
+    const { bitmask_pad } = await pg.one(
+      `SELECT utils.bitmask_pad($1::varbit, $2) AS bitmask_pad`,
+      ['101', 2]
+    );
+    expect(bitmask_pad).toMatchSnapshot();
+  });
+});

package/deploy/schemas/utils/procedures/ensure_singleton.sql

@@ -0,0 +1,29 @@
+-- Deploy schemas/utils/procedures/ensure_singleton to pg
+
+-- requires: schemas/utils/schema
+
+BEGIN;
+
+CREATE FUNCTION utils.ensure_singleton()
+  RETURNS TRIGGER
+AS $$
+DECLARE
+  sql text;
+  num int;
+BEGIN
+
+  sql = format('SELECT count(1) FROM %1I.%2I;', TG_TABLE_SCHEMA, TG_TABLE_NAME);
+  
+  EXECUTE sql
+    INTO num;
+
+  IF (num > 0) THEN 
+    RAISE EXCEPTION 'SINGLETON_TABLE';
+  END IF;
+
+  RETURN NEW;
+END;
+$$
+LANGUAGE 'plpgsql';
+
+COMMIT;

package/deploy/schemas/utils/procedures/mask_pad.sql

@@ -0,0 +1,33 @@
+-- Deploy schemas/utils/procedures/mask_pad to pg
+-- requires: schemas/utils/schema
+BEGIN;
+
+CREATE FUNCTION utils.mask_pad (bitstr text, bitlen int, pad text DEFAULT '0')
+  RETURNS text
+  AS $$
+  SELECT
+    (
+      CASE WHEN length(bitstr) > bitlen THEN
+        substring(bitstr FROM (length(bitstr) - (bitlen - 1))
+          FOR bitlen)
+      ELSE
+        lpad(bitstr, bitlen, pad)
+      END)
+$$
+LANGUAGE 'sql';
+
+CREATE FUNCTION utils.bitmask_pad (bitstr bit varying, bitlen int, pad text DEFAULT '0')
+  RETURNS bit varying
+  AS $$
+  SELECT
+    (
+      CASE WHEN length(bitstr) > bitlen THEN
+        substring(bitstr::text FROM (length(bitstr) - (bitlen - 1))
+          FOR bitlen)
+      ELSE
+        lpad(bitstr::text, bitlen, pad)
+      END)::varbit;
+$$
+LANGUAGE 'sql';
+COMMIT;
+

package/deploy/schemas/utils/procedures/throw.sql

@@ -0,0 +1,26 @@
+-- Deploy schemas/utils/procedures/throw to pg
+
+-- requires: schemas/utils/schema
+
+BEGIN;
+
+CREATE FUNCTION utils.throw()
+  RETURNS TRIGGER
+AS $$
+BEGIN
+
+  IF (TG_NARGS = 1) THEN 
+    RAISE EXCEPTION '% (%)', TG_ARGV[0], TG_TABLE_NAME;
+  END IF;
+
+  IF (TG_NARGS > 1) THEN 
+    RAISE EXCEPTION '% (%, %)', TG_ARGV[0], TG_TABLE_NAME, TG_ARGV[1];
+  END IF;
+
+  RAISE EXCEPTION 'THROWN_ERROR (%)', TG_TABLE_NAME;
+
+END;
+$$
+LANGUAGE 'plpgsql';
+
+COMMIT;

package/deploy/schemas/utils/schema.sql

@@ -0,0 +1,14 @@
+-- Deploy schemas/utils/schema to pg
+
+
+BEGIN;
+
+CREATE SCHEMA utils;
+
+GRANT USAGE ON SCHEMA utils TO public;
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA utils
+GRANT EXECUTE ON FUNCTIONS
+TO public;
+
+COMMIT;

package/jest.config.js

@@ -0,0 +1,15 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+
+  // Match both __tests__ and colocated test files
+  testMatch: ['**/?(*.)+(test|spec).{ts,tsx,js,jsx}'],
+
+  // Ignore build artifacts and type declarations
+  testPathIgnorePatterns: ['/dist/', '\\.d\\.ts$'],
+  modulePathIgnorePatterns: ['<rootDir>/dist/'],
+  watchPathIgnorePatterns: ['/dist/'],
+
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+};

package/launchql-utils.control

@@ -0,0 +1,8 @@
+# launchql-utils extension
+comment = 'launchql-utils extension'
+default_version = '0.4.6'
+module_pathname = '$libdir/launchql-utils'
+requires = 'plpgsql,launchql-verify'
+relocatable = false
+superuser = false
+  

package/launchql.plan

@@ -0,0 +1,8 @@
+%syntax-version=1.0.0
+%project=launchql-utils
+%uri=launchql-utils
+  
+schemas/utils/schema 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/utils/schema
+schemas/utils/procedures/mask_pad [schemas/utils/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/utils/procedures/mask_pad
+schemas/utils/procedures/throw [schemas/utils/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/utils/procedures/throw
+schemas/utils/procedures/ensure_singleton [schemas/utils/schema] 2021-04-25T11:50:15Z Dan Lynch <dlynch@Dans-MBP-3> # add schemas/utils/procedures/ensure_singleton

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pgpm/utils",
+  "version": "0.4.0",
+  "description": "General utility functions for PostgreSQL extensions",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "bundle": "lql package",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@pgpm/verify": "0.4.0"
+  },
+  "devDependencies": {
+    "@launchql/cli": "^4.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/launchql/extensions"
+  },
+  "homepage": "https://github.com/launchql/extensions",
+  "bugs": {
+    "url": "https://github.com/launchql/extensions/issues"
+  },
+  "gitHead": "cc9f52a335caa6e21ee7751b04b77c84ce6cb809"
+}

package/revert/schemas/utils/procedures/ensure_singleton.sql

@@ -0,0 +1,7 @@
+-- Revert schemas/utils/procedures/ensure_singleton from pg
+
+BEGIN;
+
+DROP FUNCTION utils.ensure_singleton;
+
+COMMIT;

package/revert/schemas/utils/procedures/mask_pad.sql

@@ -0,0 +1,7 @@
+-- Revert schemas/utils/procedures/mask_pad from pg
+
+BEGIN;
+
+DROP FUNCTION utils.mask_pad;
+
+COMMIT;

package/revert/schemas/utils/procedures/throw.sql

@@ -0,0 +1,7 @@
+-- Revert schemas/utils/procedures/throw from pg
+
+BEGIN;
+
+DROP FUNCTION utils.throw;
+
+COMMIT;

package/revert/schemas/utils/schema.sql

@@ -0,0 +1,7 @@
+-- Revert schemas/utils/schema from pg
+
+BEGIN;
+
+DROP SCHEMA utils CASCADE;
+
+COMMIT;

package/sql/launchql-utils--0.4.6.sql

@@ -0,0 +1,64 @@
+\echo Use "CREATE EXTENSION launchql-utils" to load this file. \quit
+CREATE SCHEMA utils;
+
+GRANT USAGE ON SCHEMA utils TO PUBLIC;
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA utils
+  GRANT EXECUTE ON FUNCTIONS TO PUBLIC;
+
+CREATE FUNCTION utils.mask_pad(bitstr text, bitlen int, pad text DEFAULT '0') RETURNS text AS $EOFCODE$
+  SELECT
+    (
+      CASE WHEN length(bitstr) > bitlen THEN
+        substring(bitstr FROM (length(bitstr) - (bitlen - 1))
+          FOR bitlen)
+      ELSE
+        lpad(bitstr, bitlen, pad)
+      END)
+$EOFCODE$ LANGUAGE sql;
+
+CREATE FUNCTION utils.bitmask_pad(bitstr pg_catalog.varbit, bitlen int, pad text DEFAULT '0') RETURNS pg_catalog.varbit AS $EOFCODE$
+  SELECT
+    (
+      CASE WHEN length(bitstr) > bitlen THEN
+        substring(bitstr::text FROM (length(bitstr) - (bitlen - 1))
+          FOR bitlen)
+      ELSE
+        lpad(bitstr::text, bitlen, pad)
+      END)::varbit;
+$EOFCODE$ LANGUAGE sql;
+
+CREATE FUNCTION utils.throw() RETURNS trigger AS $EOFCODE$
+BEGIN
+
+  IF (TG_NARGS = 1) THEN 
+    RAISE EXCEPTION '% (%)', TG_ARGV[0], TG_TABLE_NAME;
+  END IF;
+
+  IF (TG_NARGS > 1) THEN 
+    RAISE EXCEPTION '% (%, %)', TG_ARGV[0], TG_TABLE_NAME, TG_ARGV[1];
+  END IF;
+
+  RAISE EXCEPTION 'THROWN_ERROR (%)', TG_TABLE_NAME;
+
+END;
+$EOFCODE$ LANGUAGE plpgsql;
+
+CREATE FUNCTION utils.ensure_singleton() RETURNS trigger AS $EOFCODE$
+DECLARE
+  sql text;
+  num int;
+BEGIN
+
+  sql = format('SELECT count(1) FROM %1I.%2I;', TG_TABLE_SCHEMA, TG_TABLE_NAME);
+  
+  EXECUTE sql
+    INTO num;
+
+  IF (num > 0) THEN 
+    RAISE EXCEPTION 'SINGLETON_TABLE';
+  END IF;
+
+  RETURN NEW;
+END;
+$EOFCODE$ LANGUAGE plpgsql;

package/verify/schemas/utils/procedures/ensure_singleton.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/utils/procedures/ensure_singleton  on pg
+
+BEGIN;
+
+SELECT verify_function ('utils.ensure_singleton');
+
+ROLLBACK;

package/verify/schemas/utils/procedures/mask_pad.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/utils/procedures/mask_pad  on pg
+
+BEGIN;
+
+SELECT verify_function ('utils.mask_pad');
+
+ROLLBACK;

package/verify/schemas/utils/procedures/throw.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/utils/procedures/throw  on pg
+
+BEGIN;
+
+SELECT verify_function ('utils.throw');
+
+ROLLBACK;

package/verify/schemas/utils/schema.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/utils/schema  on pg
+
+BEGIN;
+
+SELECT verify_schema ('utils');
+
+ROLLBACK;