@pgpm/uuid 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-uuid
+DATA = sql/launchql-uuid--0.4.6.sql
+
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)

package/README.md

@@ -0,0 +1,5 @@
+# @pgpm/uuid
+
+UUID utilities and extensions for PostgreSQL.
+
+Provides UUID generation, validation, and utility functions for PostgreSQL applications using the LaunchQL deploy/verify/revert workflow.

package/__tests__/uuid.test.ts

@@ -0,0 +1,90 @@
+import { getConnections, PgTestClient } from 'pgsql-test';
+
+let pg: PgTestClient;
+let teardown: () => Promise<void>;
+
+beforeAll(async () => {
+  ({ pg, teardown } = await getConnections());
+
+  await pg.any(`
+    CREATE TABLE public.items (
+      id UUID DEFAULT uuids.pseudo_order_uuid(),
+      name TEXT,
+      seed TEXT,
+      custom_id UUID
+    );
+
+    CREATE TABLE public.items_seeded (
+      id UUID,
+      tenant TEXT
+    );
+
+    CREATE TRIGGER set_custom_id
+    BEFORE INSERT ON public.items
+    FOR EACH ROW
+    EXECUTE FUNCTION uuids.trigger_set_uuid_seed('custom_id', 'seed');
+
+    CREATE TRIGGER set_id_from_tenant
+    BEFORE INSERT ON public.items_seeded
+    FOR EACH ROW
+    EXECUTE FUNCTION uuids.trigger_set_uuid_related_field('id', 'tenant');
+  `);
+});
+
+afterAll(async () => {
+  try {
+    await teardown();
+  } catch (e) {
+    console.error('Teardown failed:', e);
+  }
+});
+
+beforeEach(() => pg.beforeEach());
+afterEach(() => pg.afterEach());
+
+describe('uuids.pseudo_order_uuid()', () => {
+  it('generates a valid UUID', async () => {
+    const { pseudo_order_uuid } = await pg.one(`
+      SELECT uuids.pseudo_order_uuid() AS pseudo_order_uuid
+    `);
+    expect(pseudo_order_uuid).toMatch(
+      /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[a-f0-9]{4}-[a-f0-9]{12}$/
+    );
+  });
+});
+
+describe('uuids.pseudo_order_seed_uuid(seed)', () => {
+  it('generates a valid UUID from a seed', async () => {
+    const { pseudo_order_seed_uuid } = await pg.one(
+      `SELECT uuids.pseudo_order_seed_uuid($1) AS pseudo_order_seed_uuid`,
+      ['tenant123']
+    );
+    expect(pseudo_order_seed_uuid).toMatch(
+      /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[a-f0-9]{4}-[a-f0-9]{12}$/
+    );
+  });
+});
+
+describe('uuids.trigger_set_uuid_seed', () => {
+  it('sets custom_id based on static seed', async () => {
+    const { custom_id } = await pg.one(
+      `INSERT INTO public.items (name, seed) VALUES ($1, $2) RETURNING custom_id`,
+      ['Item A', 'my-seed']
+    );
+    expect(custom_id).toMatch(
+      /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[a-f0-9]{4}-[a-f0-9]{12}$/
+    );
+  });
+});
+
+describe('uuids.trigger_set_uuid_related_field', () => {
+  it('sets id based on tenant column', async () => {
+    const { id } = await pg.one(
+      `INSERT INTO public.items_seeded (tenant) VALUES ($1) RETURNING id`,
+      ['tenant-42']
+    );
+    expect(id).toMatch(
+      /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[a-f0-9]{4}-[a-f0-9]{12}$/
+    );
+  });
+});

package/deploy/schemas/uuids/procedures/pseudo_order_seed_uuid.sql

@@ -0,0 +1,50 @@
+-- Deploy schemas/uuids/procedures/pseudo_order_seed_uuid to pg
+
+-- requires: schemas/uuids/schema
+
+-- The first 2 characters of the UUID value comes from 
+-- the MD5 hash of the uuid_seed. The next
+-- 2 characters are the MD5 hash of the concatenation
+-- of the current year and week number. This value is,
+-- of course, static over a week. The remaining of the
+--  UUID value comes from the MD5 of a random value and
+-- the current time at a precision of 1us. The third field
+-- is prefixed with a “4” to indicate it is a version 4 UUID type.
+
+BEGIN;
+
+CREATE FUNCTION uuids.pseudo_order_seed_uuid(
+	seed text
+)
+    RETURNS uuid
+AS $$
+DECLARE
+    new_uuid char(36);
+    md5_str char(32);
+    md5_str2 char(32);
+    uid text;
+BEGIN
+    md5_str := md5(concat(random(), now()));
+    md5_str2 := md5(concat(random(), now()));
+    
+    new_uuid := concat(
+        LEFT (md5(seed), 2),
+        LEFT (md5(concat(extract(year FROM now()), extract(week FROM now()))), 2),
+        substring(md5_str, 1, 4),
+        '-',
+        substring(md5_str, 5, 4),
+        '-4',
+        substring(md5_str2, 9, 3),
+        '-',
+        substring(md5_str, 13, 4),
+        '-', 
+        substring(md5_str2, 17, 12)
+    );
+    RETURN new_uuid;
+END;
+$$
+LANGUAGE plpgsql VOLATILE;
+
+COMMENT ON FUNCTION uuids.pseudo_order_seed_uuid IS 'Pseudo Ordered UUID with a seed. Good for multi-tenant scenarios, other wise use non-seed.';
+
+COMMIT;

package/deploy/schemas/uuids/procedures/pseudo_order_uuid.sql

@@ -0,0 +1,27 @@
+-- Deploy schemas/uuids/procedures/pseudo_order_uuid to pg
+
+-- requires: schemas/uuids/schema
+
+BEGIN;
+
+CREATE FUNCTION uuids.pseudo_order_uuid()
+    RETURNS uuid
+AS $$
+DECLARE
+    new_uuid char(36);
+    md5_str char(32);
+    md5_str2 char(32);
+BEGIN
+    md5_str := md5(concat(random(), now()));
+    md5_str2 := md5(concat(random(), now()));
+    new_uuid := concat(
+    LEFT (md5(concat(extract(year FROM now()), extract(week FROM now()))), 4),
+    LEFT (md5_str, 4), '-', substring(md5_str, 5, 4), '-4', substring(md5_str2, 9, 3), '-', substring(md5_str, 13, 4), '-', substring(md5_str2, 17, 12));
+    RETURN new_uuid;
+END;
+$$
+LANGUAGE plpgsql VOLATILE;
+
+COMMENT ON FUNCTION uuids.pseudo_order_seed_uuid IS 'Pseudo Ordered UUID';
+
+COMMIT;

package/deploy/schemas/uuids/procedures/trigger_set_uuid_related_field.sql

@@ -0,0 +1,29 @@
+-- Deploy schemas/uuids/procedures/trigger_set_uuid_related_field to pg
+
+-- requires: schemas/uuids/schema
+-- requires: schemas/uuids/procedures/pseudo_order_seed_uuid
+
+BEGIN;
+
+-- https://dba.stackexchange.com/questions/61271/how-to-access-new-or-old-field-given-only-the-fields-name
+-- https://dba.stackexchange.com/questions/82039/assign-to-new-by-key-in-a-postgres-trigger/82044#82044
+-- https://stackoverflow.com/questions/7711432/how-to-set-value-of-composite-variable-field-using-dynamic-sql
+
+-- usage CREATE TRIGGER ...
+-- EXECUTE PROCEDURE uuids.trigger_set_uuid_seed ('id', 'database_id');
+
+CREATE FUNCTION uuids.trigger_set_uuid_related_field()
+RETURNS TRIGGER AS $$
+DECLARE
+    _seed_column text := to_json(NEW) ->> TG_ARGV[1];
+BEGIN
+    IF _seed_column IS NULL THEN
+        RAISE EXCEPTION 'UUID seed is NULL on table %', TG_TABLE_NAME;
+    END IF;
+    NEW := NEW #= (TG_ARGV[0] || '=>' || uuids.pseudo_order_seed_uuid(_seed_column))::hstore;
+    RETURN NEW;
+END;
+$$
+LANGUAGE 'plpgsql' VOLATILE;
+
+COMMIT;

package/deploy/schemas/uuids/procedures/trigger_set_uuid_seed.sql

@@ -0,0 +1,24 @@
+-- Deploy schemas/uuids/procedures/trigger_set_uuid_seed to pg
+
+-- requires: schemas/uuids/schema
+-- requires: schemas/uuids/procedures/pseudo_order_seed_uuid
+
+BEGIN;
+
+-- https://dba.stackexchange.com/questions/61271/how-to-access-new-or-old-field-given-only-the-fields-name
+-- https://dba.stackexchange.com/questions/82039/assign-to-new-by-key-in-a-postgres-trigger/82044#82044
+-- https://stackoverflow.com/questions/7711432/how-to-set-value-of-composite-variable-field-using-dynamic-sql
+
+-- usage CREATE TRIGGER ...
+-- EXECUTE PROCEDURE uuids.trigger_set_uuid_seed ('id', '41c33217-a5e5-46d1-c8db-62a563cba3af');
+
+CREATE FUNCTION uuids.trigger_set_uuid_seed()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW := NEW #= (TG_ARGV[0] || '=>' || uuids.pseudo_order_seed_uuid(TG_ARGV[1]))::hstore;
+    RETURN NEW;
+END;
+$$
+LANGUAGE 'plpgsql' VOLATILE;
+
+COMMIT;

package/deploy/schemas/uuids/schema.sql

@@ -0,0 +1,16 @@
+-- Deploy schemas/uuids/schema to pg
+
+
+BEGIN;
+
+CREATE SCHEMA uuids;
+
+GRANT USAGE ON SCHEMA uuids
+TO public;
+
+ALTER DEFAULT PRIVILEGES
+IN SCHEMA uuids
+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-uuid.control

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

package/launchql.plan

@@ -0,0 +1,9 @@
+%syntax-version=1.0.0
+%project=launchql-uuid
+%uri=launchql-uuid
+  
+schemas/uuids/schema 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/schema
+schemas/uuids/procedures/pseudo_order_seed_uuid [schemas/uuids/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/pseudo_order_seed_uuid
+schemas/uuids/procedures/pseudo_order_uuid [schemas/uuids/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/pseudo_order_uuid
+schemas/uuids/procedures/trigger_set_uuid_related_field [schemas/uuids/schema schemas/uuids/procedures/pseudo_order_seed_uuid] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/trigger_set_uuid_related_field
+schemas/uuids/procedures/trigger_set_uuid_seed [schemas/uuids/schema schemas/uuids/procedures/pseudo_order_seed_uuid] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/trigger_set_uuid_seed

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pgpm/uuid",
+  "version": "0.4.0",
+  "description": "UUID utilities and extensions for PostgreSQL",
+  "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/uuids/procedures/pseudo_order_seed_uuid.sql

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

package/revert/schemas/uuids/procedures/pseudo_order_uuid.sql

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

package/revert/schemas/uuids/procedures/trigger_set_uuid_related_field.sql

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

package/revert/schemas/uuids/procedures/trigger_set_uuid_seed.sql

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

package/revert/schemas/uuids/schema.sql

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

package/sqitch.plan

@@ -0,0 +1,9 @@
+%syntax-version=1.0.0
+%project=launchql-uuid
+%uri=launchql-uuid
+  
+schemas/uuids/schema 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/schema
+schemas/uuids/procedures/pseudo_order_seed_uuid [schemas/uuids/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/pseudo_order_seed_uuid
+schemas/uuids/procedures/pseudo_order_uuid [schemas/uuids/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/pseudo_order_uuid
+schemas/uuids/procedures/trigger_set_uuid_related_field [schemas/uuids/schema schemas/uuids/procedures/pseudo_order_seed_uuid] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/trigger_set_uuid_related_field
+schemas/uuids/procedures/trigger_set_uuid_seed [schemas/uuids/schema schemas/uuids/procedures/pseudo_order_seed_uuid] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/uuids/procedures/trigger_set_uuid_seed

package/sql/launchql-uuid--0.4.6.sql

@@ -0,0 +1,72 @@
+\echo Use "CREATE EXTENSION launchql-uuid" to load this file. \quit
+CREATE SCHEMA uuids;
+
+GRANT USAGE ON SCHEMA uuids TO PUBLIC;
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA uuids
+  GRANT EXECUTE ON FUNCTIONS TO PUBLIC;
+
+CREATE FUNCTION uuids.pseudo_order_seed_uuid(seed text) RETURNS uuid AS $EOFCODE$
+DECLARE
+    new_uuid char(36);
+    md5_str char(32);
+    md5_str2 char(32);
+    uid text;
+BEGIN
+    md5_str := md5(concat(random(), now()));
+    md5_str2 := md5(concat(random(), now()));
+    
+    new_uuid := concat(
+        LEFT (md5(seed), 2),
+        LEFT (md5(concat(extract(year FROM now()), extract(week FROM now()))), 2),
+        substring(md5_str, 1, 4),
+        '-',
+        substring(md5_str, 5, 4),
+        '-4',
+        substring(md5_str2, 9, 3),
+        '-',
+        substring(md5_str, 13, 4),
+        '-', 
+        substring(md5_str2, 17, 12)
+    );
+    RETURN new_uuid;
+END;
+$EOFCODE$ LANGUAGE plpgsql VOLATILE;
+
+COMMENT ON FUNCTION uuids.pseudo_order_seed_uuid IS 'Pseudo Ordered UUID with a seed. Good for multi-tenant scenarios, other wise use non-seed.';
+
+CREATE FUNCTION uuids.pseudo_order_uuid() RETURNS uuid AS $EOFCODE$
+DECLARE
+    new_uuid char(36);
+    md5_str char(32);
+    md5_str2 char(32);
+BEGIN
+    md5_str := md5(concat(random(), now()));
+    md5_str2 := md5(concat(random(), now()));
+    new_uuid := concat(
+    LEFT (md5(concat(extract(year FROM now()), extract(week FROM now()))), 4),
+    LEFT (md5_str, 4), '-', substring(md5_str, 5, 4), '-4', substring(md5_str2, 9, 3), '-', substring(md5_str, 13, 4), '-', substring(md5_str2, 17, 12));
+    RETURN new_uuid;
+END;
+$EOFCODE$ LANGUAGE plpgsql VOLATILE;
+
+COMMENT ON FUNCTION uuids.pseudo_order_seed_uuid IS 'Pseudo Ordered UUID';
+
+CREATE FUNCTION uuids.trigger_set_uuid_related_field() RETURNS trigger AS $EOFCODE$
+DECLARE
+    _seed_column text := to_json(NEW) ->> TG_ARGV[1];
+BEGIN
+    IF _seed_column IS NULL THEN
+        RAISE EXCEPTION 'UUID seed is NULL on table %', TG_TABLE_NAME;
+    END IF;
+    NEW := NEW #= (TG_ARGV[0] || '=>' || uuids.pseudo_order_seed_uuid(_seed_column))::hstore;
+    RETURN NEW;
+END;
+$EOFCODE$ LANGUAGE plpgsql VOLATILE;
+
+CREATE FUNCTION uuids.trigger_set_uuid_seed() RETURNS trigger AS $EOFCODE$
+BEGIN
+    NEW := NEW #= (TG_ARGV[0] || '=>' || uuids.pseudo_order_seed_uuid(TG_ARGV[1]))::hstore;
+    RETURN NEW;
+END;
+$EOFCODE$ LANGUAGE plpgsql VOLATILE;

package/verify/schemas/uuids/procedures/pseudo_order_seed_uuid.sql

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

package/verify/schemas/uuids/procedures/pseudo_order_uuid.sql

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

package/verify/schemas/uuids/procedures/trigger_set_uuid_related_field.sql

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

package/verify/schemas/uuids/procedures/trigger_set_uuid_seed.sql

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

package/verify/schemas/uuids/schema.sql

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