{"id":17384,"library":"tiny-fixtures","title":"Tiny Fixtures","description":"`tiny-fixtures` is a lightweight JavaScript/TypeScript library designed to simplify the creation and management of database fixtures specifically for testing environments. Currently at version 0.3.0, it is built to integrate with PostgreSQL databases, relying on `node-postgres` connection pools for its operations. The package's primary export is the `tinyFixtures` function, which, when initialized with a database pool, returns a `createFixtures` function. This function facilitates the generation of `setup` and `teardown` routines for specified tables and data arrays. A key differentiator is its robust handling of foreign key relationships, allowing testers to reference IDs of newly inserted parent records when creating child fixtures. The library aims to provide clean, isolated test data for each test run while importantly preserving existing data in development databases, thereby enhancing the local development workflow. It maintains a 'tiny' footprint by emphasizing explicit control over fixture ordering, particularly for relational data.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/antman261/tiny-fixtures","tags":["javascript","testing","postgres","fixtures","typescript","backend","back-end"],"install":[{"cmd":"npm install tiny-fixtures","lang":"bash","label":"npm"},{"cmd":"yarn add tiny-fixtures","lang":"bash","label":"yarn"},{"cmd":"pnpm add tiny-fixtures","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for database connection pooling, as tiny-fixtures is built on node-postgres.","package":"pg","optional":false}],"imports":[{"note":"The library is written in TypeScript and primarily consumed as an ESM module. While CommonJS might technically work, ESM imports are the recommended and most compatible approach in modern Node.js projects.","wrong":"const { tinyFixtures } = require('tiny-fixtures');","symbol":"tinyFixtures","correct":"import { tinyFixtures } from 'tiny-fixtures';"},{"note":"Type import for the object returned when initializing tinyFixtures with a pool.","symbol":"FixtureManager","correct":"import type { FixtureManager } from 'tiny-fixtures';"},{"note":"Type import for the foreign key reference object returned by `getRefByKey`.","symbol":"Ref","correct":"import type { Ref } from 'tiny-fixtures';"}],"quickstart":{"code":"import { tinyFixtures } from 'tiny-fixtures';\nimport { Pool } from 'pg'; // Assuming 'pg' is installed and configured\nimport { expect } from 'chai'; // Assuming a testing framework like Mocha/Chai\n\n// Dummy connection pool (replace with your actual database pool)\nconst pool = new Pool({\n  user: process.env.DB_USER ?? 'testuser',\n  host: process.env.DB_HOST ?? 'localhost',\n  database: process.env.DB_NAME ?? 'testdb',\n  password: process.env.DB_PASSWORD ?? 'testpassword',\n  port: parseInt(process.env.DB_PORT ?? '5432', 10),\n});\n\n// Dummy function to fetch users (replace with actual DB query)\nconst getUsers = async () => {\n  const client = await pool.connect();\n  try {\n    const res = await client.query('SELECT id, email, username FROM users;');\n    return res.rows;\n  } finally {\n    client.release();\n  }\n};\n\nconst getUserMessages = async (userId: number) => {\n  const client = await pool.connect();\n  try {\n    const res = await client.query('SELECT message FROM user_messages WHERE user_id = $1;', [userId]);\n    return res.rows;\n  } finally {\n    client.release();\n  }\n}\n\nconst { createFixtures } = tinyFixtures(pool);\n\ndescribe('my test cases with foreign keys', () => {\n  const [setupUserFixtures, teardownUserFixtures, users] = createFixtures('users', [\n    {\n      email: 'foo@bar.co',\n      username: 'tinyAnt'\n    }, {\n      email: 'bar@foo.co',\n      username: 'antTiny',\n    }\n  ]);\n\n  const [setupUserMessageFixtures, teardownUserMessageFixtures] = createFixtures(\n    'user_messages',\n    [{\n        user_id: users[0].getRefByKey('id'),\n        message: 'Foobar did the bar foo good',\n      },\n      {\n        user_id: users[0].getRefByKey('id'),\n        message: 'I am a meat popsicle', \n    }]\n  );\n\n  beforeEach(async () => {\n    await setupUserFixtures();\n    await setupUserMessageFixtures();\n  });\n\n  afterEach(async () => {\n    await teardownUserMessageFixtures();\n    await teardownUserFixtures();\n  });\n\n  it('should have a user with two messages, and one with none', async () => {\n    const dbUsers = await getUsers();\n    expect(dbUsers).to.have.length(2);\n\n    const messagesForUser1 = await getUserMessages(dbUsers[0].id);\n    const messagesForUser2 = await getUserMessages(dbUsers[1].id);\n\n    expect(messagesForUser1).to.have.length(2);\n    expect(messagesForUser2).to.have.length(0);\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to use `tiny-fixtures` to create related data across two tables (`users` and `user_messages`) using foreign key references in a test suite, ensuring clean data for each test run."},"warnings":[{"fix":"Ensure your database is PostgreSQL and you are passing a correctly configured `node-postgres` connection pool (from the `pg` package) to `tinyFixtures`.","message":"Tiny Fixtures is currently only tested and compatible with PostgreSQL databases. It specifically expects a `node-postgres` connection pool for database interactions. Using it with other SQL dialects (e.g., MySQL, SQLite) or alternative ORMs/database drivers may lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Strictly follow the dependency order: `await setupParentFixtures(); await setupChildFixtures();` in `beforeEach` hooks, and `await teardownChildFixtures(); await teardownParentFixtures();` in `afterEach` hooks.","message":"When defining fixtures across multiple tables with foreign key relationships, the order in which `setup` and `teardown` functions are called is crucial for maintaining referential integrity. Parent table setups must always precede child table setups, and conversely, child table teardowns must precede parent table teardowns.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import { tinyFixtures } from 'tiny-fixtures';`.","cause":"Attempting to use `require()` for an ESM module or incorrect named import syntax in a CommonJS context.","error":"TypeError: tinyFixtures is not a function"},{"fix":"Verify that you are correctly destructuring the third array element, e.g., `const [setup, teardown, users] = createFixtures('users', [...]);`, and then using `users[index].getRefByKey('id')` to get the reference.","cause":"This error typically occurs when `getRefByKey` is called on an object that is not a valid fixture reference or if the third return value from `createFixtures` was not correctly destructured or used out of scope.","error":"TypeError: Cannot read properties of undefined (reading 'getRefByKey')"},{"fix":"Double-check your `pg.Pool` configuration (host, port, user, password, database) and ensure the PostgreSQL database server is running and accessible from where your tests are executed.","cause":"The `node-postgres` connection pool provided to `tinyFixtures` is unable to establish a connection to the PostgreSQL database, often due to incorrect connection parameters, the database server not running, or firewall issues.","error":"Error: connect ECONNREFUSED"}],"ecosystem":"npm","meta_description":null}