DEV Community: Sebastian Wessel

How-To Spec-Driven AI Development

Sebastian Wessel — Thu, 28 May 2026 17:02:50 +0000

AI does not fail only because it is unreliable.

It often fails because we ask it to fulfill expectations we never explained.

That is the core of spec-driven development for me.

Not process. Not documentation theater. Not a return to slow software delivery.

Spec-driven development is the practice of giving AI the information it needs to do the work correctly: purpose, context, boundaries, constraints, architecture, business expectations, acceptance criteria, and review gates.

If the AI should meet an expectation, the expectation must be available to the AI.

That sounds obvious.

In practice, it is where many AI-assisted projects break.

What This Covers

The Goal Is Not More Code
AI Can Only Meet Expectations It Can See
Human Language Becomes The Interface
Spec-Driven Development Starts With The Knowns
Human Work Moves Up A Level
Good Specs Make Expectations Executable
Planning Makes Work Delegatable
Implementation Should Not Invent
Review Becomes A Trust Pipeline
What Works For Me
Open Questions To Handle
Conclusion

The Goal Is Not More Code

The goal is not to produce more code faster.

That is too small.

Enterprise software has users, data, security boundaries, compliance pressure, legacy systems, audit questions, operations, budgets, deadlines, and people who need to understand why a system behaves the way it behaves.

AI can make implementation faster, but that is only the shallow part.

Used well, AI can also help make enterprise requirements visible. It can check whether security boundaries are covered. It can explain how data flows through the system. It can point to tests. It can summarize architectural decisions. It can prepare audit evidence. It can answer a human who asks: "How is this topic covered? Show me. Explain it. Prove it."

That is the more interesting goal.

AI-assisted delivery should help teams build software that meets expectations, respects constraints, can be explained, can be tested, and can be audited.

That requires a shared knowledge layer.

For me, that is one of the most important roles of a spec. It is centralized, comprehensive knowledge for humans and AI at the same time. People can see the intent, boundaries, decisions, and acceptance criteria. AI agents can use the same source to implement, explain, test, and prove the work.

But that only works if the AI has the right information to reason from.

AI Can Only Meet Expectations It Can See

If you know it, write it down.

That sounds almost too simple, but it is the center of the whole workflow.

If you know the business reason, write it down.

If you know the technical boundary, write it down.

If you know the existing architecture pattern, write it down.

If you know the security constraint, write it down.

If you know what would make the result wrong, write it down.

AI agents do not share your memory. They do not know the meeting, the political constraint, the legacy scar, the product promise, the audit pressure, or the architecture rule unless that information is present in the task.

Start with the knowns:

purpose, intent, and business point of view
boundaries, non-goals, and existing context
tech stack and architecture decisions
security, compliance, and operational constraints
acceptance criteria and review questions

The better the expectation is described, the less the AI has to guess.

And guessing is where delivery risk starts.

Human Language Becomes The Interface

Programming languages have always been an interface between humans and computers.

But they were never a native language for either side.

Humans think in goals, constraints, tradeoffs, examples, risks, and stories. Then we translate that into TypeScript, Python, SQL, or whatever stack the system needs. The computer still needs parsers, compilers, interpreters, runtimes, operating systems, and machines that execute instructions at a much lower level.

Programming languages are the middle layer both sides can use.

They are powerful, precise, and necessary.

But for humans, they are still a second language.

For decades, software development was mostly one directional. The human translated intent into code. The machine accepted or rejected it. The feedback loop existed, but the computer did not discuss intent with us in our own language.

That is the paradigm shift.

With AI-assisted development, human language becomes a two-way interface. We can describe goals, constraints, behavior, examples, risks, and review questions. The AI can respond, ask clarifying questions, explain tradeoffs, inspect code, generate tests, summarize architecture, and help translate the result into implementation.

This does not mean programming languages stop mattering.

They still matter a lot. Runtime behavior, type systems, package ecosystems, performance, security, deployment, and maintainability are still real.

But from the human interface point of view, the higher-level artifact is no longer only the code.

It is the spec, the architecture, the acceptance criteria, the review checklist, and the reusable instructions that tell agents what is expected and how their work will be checked.

Spec-Driven Development Starts With The Knowns

Software teams have always planned.

Waterfall planned heavily before implementation. Agile reacted against that and moved planning closer to delivery. User stories, architecture decision records, RFCs, tickets, acceptance criteria, and sprint planning all came from the same basic problem:

Software is too expensive to build by accident.

Spec-driven development starts with the knowns.

That gives it part of the strength of waterfall: precision, completeness where completeness is possible, and a serious attempt to make expectations explicit before expensive work starts.

But it should not inherit waterfall's weakness.

The spec is not written in stone upfront.

It is a living document.

That is where it takes the useful part of agile. You do not need to describe the full final system before the first useful implementation happens. You describe what is known now, implement against that, learn, and extend the spec for the next feature, the next workflow, the next constraint, or the next architectural decision.

The important difference is that iteration does not mean guessing.

Each iteration should still make its knowns explicit before implementation starts.

Vibe coding is one symptom. It works for exploration, but it breaks as a delivery model when the human expects the AI to know business intent, architecture rules, security constraints, and product expectations that were never provided. Spec-driven development changes the question from "can the AI guess enough?" to "did we give the AI the right information, boundaries, and checks?"

Planning used to align humans with humans.

Spec-driven development must align humans with humans and humans with AI.

Human Work Moves Up A Level

Once the knowns are explicit, the human role changes.

The most valuable human work moves closer to purpose, business pressure, architecture, and risk.

The work becomes explaining what outcome matters, where the tradeoffs are, and how the existing system behaves. It also means making boundaries, failure modes, and delivery constraints explicit: maintainability, operations, compliance, ownership, and risk.

That does not make engineering or architecture judgment less important.

It makes that thinking more important.

If you only measure your value by how many lines you personally write, AI feels like a threat. If you measure your value by how well you turn business pressure into robust systems, AI becomes leverage.

The human job is no longer only to produce the implementation.

The human job is to make the expectation clear enough that implementation can be delegated, checked, explained, and improved.

The better humans define purpose, boundaries, and risks, the better AI can handle the workflow: write the spec, plan the work, implement scoped tickets, and review the result.

Good Specs Make Expectations Executable

The obvious question comes quickly: how do I get to a good spec?

That was hard for me.

My first real contact with spec-driven development came through Kiro specs. Later I looked at GitHub Spec Kit, Tessl's spec-driven development workflow, and similar approaches. Conceptually, I liked the direction immediately: requirements, design, tasks, implementation, review.

But in practice, it still required too much manual human work.

Too much writing. Too many manual steps. Too much structure that busy teams will not consistently fill with enough quality under delivery pressure.

Those tools are valuable from a conceptual and technical perspective. But for enterprise delivery, the workflow has to be feasible. If it depends on humans manually writing perfect specs, tickets, and review notes every time, it will fail.

That is why I think the spec workflow itself must be AI-assisted and automated.

The spec is the main place where human judgment belongs, but the AI should help create it, challenge it, repair it, and review it. Otherwise humans still have to write specs, repair specs, collect context, split plans into tickets, police scope, compare implementation against intent, and keep teams aligned.

That is exactly the work that becomes inconsistent when people are tired, rushed, or under delivery pressure.

This is why I created sebastianwessel/skills: not to replace senior judgment, but to move senior judgment into reusable context, gates, and instructions.

Skills Turn Judgment Into Guidance

My approach is not to ask an AI to "write a good spec" and hope for the best.

The skill gives the AI the operating model for writing and maintaining specs. It tells the AI what good means: concise, gap-free, traceable, implementation-ready, and explicit enough that agents do not have to guess.

The human provides the intent, context, constraints, and decisions.

The AI uses the skill to turn that input into precise specs, ask focused questions, find gaps, structure the material, maintain consistency, and keep the source of truth clean as the project evolves.

That is the division of work I want: humans decide what matters, and AI handles the disciplined spec work required to make those expectations usable.

Writing Specs Is An Iterative Loop

Writing a spec is not one big document dump.

It is an iterative loop from top to bottom.

I start with the overall purpose: what should exist, why it matters, who it is for, which business outcome it supports, and which constraints are already known.

Then I move down into features, workflows, boundaries, interfaces, data, failure modes, security, operations, and acceptance criteria.

At each level, I do not use the AI only as a task fulfiller.

I use it as a sparring partner. I want it to challenge my proposal, push back on weak assumptions, and tell me where my idea is not precise enough yet:

Where are the gaps?
What would you challenge in this proposal?
Which unhappy paths are missing?
What should happen when this step fails?
Which interfaces or dependencies are unclear?
Which risks would you expect in production?

That is where AI is extremely useful. It can hold a larger context than a human can comfortably keep in mind. It can follow dependency trees, interfaces, flows, and edge cases. It can repeatedly ask the boring questions humans skip when they are tired.

This is what my spec-architect skill is built around. A spec is not ready because it sounds plausible. It is ready when an agent can implement from it without deciding behavior, interfaces, failures, security, data, recovery, release, observability, or tests.

Reviewing Specs Is Also An AI Workflow

I do not want to manually read every spec document line by line.

That is not the best use of human attention.

Instead, I ask the AI precise questions. Explain this flow step by step. Show me the risky assumptions. Visualize the dependencies. Find unclear interfaces. Suggest simpler patterns. Look for scaling and performance issues. Check whether the acceptance criteria actually prove the behavior.

Basically, I ask the AI the questions I would ask during a manual review.

The important difference is that those questions can become reusable: a skill, a checklist, a Markdown file, a review gate, or a project convention.

That is the leverage.

Human review moves from reading everything manually to improving the review system.

Planning Makes Work Delegatable

A spec is not yet a delivery plan.

Planning turns the source of truth into work that can be delegated.

This is what teams have tried to do for years with Jira tickets, refinements, planning sessions, and acceptance criteria. The intention was right: create work items with enough context that implementation becomes predictable.

But it was always expensive.

Good tickets require real context: acceptance criteria, boundaries, dependencies, and enough detail to reduce interpretation without becoming impossible to maintain.

In many teams, that never worked consistently.

Spec-driven planning can finally achieve what agile planning tried to achieve because the planning can be generated from the spec.

The human effort moves into spec creation, where it belongs.

That is a better place for it. The spec is the long-lived source of truth. Plans and tickets are temporary: they orchestrate and track a short implementation period.

My spec-implementation-planner skill exists for that step.

The planner should slice work horizontally first to create foundations and interfaces for safe parallel work. Then it should create vertical tickets that are small, isolated, and end-to-end useful. Each slice should move the system toward a working feature, not just produce disconnected technical fragments.

The core of planning is enablement: make autonomous implementation safe, parallel, traceable, and focused on working outcomes.

If a ticket cannot be filled from the approved spec, the answer is not to let the implementer guess.

The answer is to go back to the spec.

Implementation Should Not Invent

Implementation is where AI can move very fast.

That speed is only useful when the work is isolated and precise.

An implementation ticket should be a focused piece of work with defined scope, defined interfaces, clear acceptance criteria, and no room for interpretation. The implementer should know what can be read, what can be changed, which dependencies must be ready, and how success will be verified.

That is why this works so well with test-driven development.

Explicit interfaces and expectations make it much easier to write the tests first, implement against them, and verify that the behavior matches the ticket. The AI can iterate inside a narrow boundary instead of roaming through the system.

My spec-ticket-implementation skill is intentionally strict: implement one approved ticket, respect read and write scope, check dependencies, cover happy and unhappy paths, verify acceptance criteria, and stop when behavior is missing.

An AI implementer should not silently become the person deciding product behavior, architecture, security, and release strategy because the ticket was vague.

If implementation needs a decision that is not in the spec or ticket, that is not implementation work.

That is a spec or plan gap.

The output should include evidence: changed files, tests, verification commands, acceptance coverage, and blockers. That evidence becomes the input for review.

Review Becomes A Trust Pipeline

Review is not one final human checkpoint.

Review happens across the whole pipeline.

Specs are reviewed for gaps and ambiguity. Plans are reviewed for scope, dependencies, and parallel safety. Implementation tickets have preflight and done gates. Final implementation review checks whether the implemented paths still match the approved spec and plan.

That is what spec-implementation-review is for. It compares the implementation path to the specs, verifies there was no drift, checks that the expected behavior was implemented, and makes sure the different ticket slices work together to fulfill the original expectations.

A reviewer can ask AI:

Is the spec itself clear, complete, and free of contradictions?
Does the implementation match the approved spec, plan, and architecture?
Which edge cases, bugs, failure modes, or evidence gaps remain?
Are security, compliance, data, and operational concerns covered?
Can findings route back to a ticket, plan gap, or spec gap?

This is where I would push hard against a common argument.

"I am better than AI at reviewing code" is usually the wrong conclusion.

When a human finds something AI missed, that does not prove the human is generally better at review. It usually proves that the human had context, experience, suspicion, or focus that was not available to the AI in that run.

That is not magic. That is knowledge.

The same is true between humans. An expert sees things a junior developer misses because the expert has more context, patterns, and prior failures in their head. AI is not different in that regard. It needs the right knowledge, the right focus, and the right review instruction.

So the useful question is not "why did the AI miss this?"

The useful question is: "what did I fail to give the AI, and how do I make sure it has that knowledge next time?"

Human intervention in planning, implementation, or review should increasingly prioritize improving the AI capability itself: better specs, better context packages, better reusable prompts, better gates, better tests, and better review skills.

That is where the cost changes.

A human review is expensive, limited, and easy to skip under pressure. A reusable AI-supported check can become part of the regular workflow. It can run more often. It can be improved when it misses something. It can grow with the system.

Over time, the important questions are no longer asked only a few times by tired humans. They become integrated into delivery as a repetitive pipeline that runs again and again.

This is how software becomes better tested, more reliable, and more predictable.

The goal is to make AI trustable: not by hoping, but by giving it context, checks, and feedback loops.

What Works For Me

This is still a young workflow, but a few patterns already work very well for me.

Use different reasoning levels for different jobs. I like medium reasoning for creating and extending specs because it keeps momentum. For review, cleanup, refactoring, gap finding, and quality gates, I prefer high reasoning. That is where I want the AI to slow down, follow paths step by step, judge honestly, and not optimize for making me happy.

Always ask questions. Ask the AI to explain flows, find gaps, challenge your proposal, inspect unhappy paths, check scaling limits, and self-reflect on weak evidence. I explicitly ask it to reason, judge, disagree when needed, and be honest about uncertainty.

Use independent models when possible. Write with one model family and review with another. My personal experience is that GPT-5.5-style models write stronger specs for this kind of work because they follow instructions more strictly and are less likely to optimize for pleasing the user. Claude models often feel more eager to start implementing or guess missing intent. That can be useful in other modes, but for specs I want discipline first.

Persist what works. If a review question is useful once, turn it into a checklist, skill, Markdown file, or project convention. Do not rely on memory. The point is to make the AI better next time.

Stop asking: how do I improve this implementation? Start asking: how do I improve the AI system that creates, checks, and improves implementations?

That mindset shift is the whole game.

Open Questions To Handle

I do not think spec-driven development breaks when the workflow above is followed seriously.

But there are still operating questions teams have to solve.

Team spec creation. How do multiple people contribute without losing alignment? Who owns the source of truth? How do product, architecture, security, and engineering decisions get merged without becoming a noisy document pile?
Project knowledge base. Specs should grow beyond feature documents. They should include business context, project history, architecture rules, operational decisions, security assumptions, and the reusable knowledge agents need to work well.
Versioning. Git is a good foundation because specs should live close to the system and be reviewed like other source artifacts. But teams still need better ways to quickly understand how expectations changed over time, which decisions moved, and which implementation plans were affected.

Those questions are not reasons to avoid spec-driven development.

They are reasons to treat specs as a serious delivery asset.

Conclusion

The enterprise impact is not "developers wrote more documents".

That would be a terrible result.

The impact is delivery that can be explained before, during, and after implementation. Specs make expectations, scope, and tradeoffs visible earlier. They make work clearer, decisions more explicit, and AI adoption less like a pile of experiments and more like a delivery capability an organization can understand.

But the real game changer is the economics.

Spec-driven development makes speed and quality move together instead of fighting each other. Implementation gets faster, but quality control also becomes more repeatable. Reviews, checks, gap analysis, acceptance validation, and proof can run as an autonomous pipeline instead of depending only on scarce human review time.

The same quality questions can be asked again and again. The review system can improve when it misses something. The knowledge can be reused across teams and projects. Quality control becomes cheaper, more frequent, and more consistent over time.

Personally, I have fully switched my personal and open-source work to spec-driven development.

That shift was honestly mind-blowing.

The real unlock was not "AI writes code now". It was changing my reaction when the AI got something wrong.

Instead of blaming the AI, I started asking: what did I fail to give it? Which context was missing? Which expectation was unclear? Which review question should become reusable? Which part of the workflow needs to improve so this does not happen again?

I get better results than I would by manually coding everything myself, and I deliver faster. Work that previously would have taken me months, sometimes years, can now move toward a production-ready product in a couple of focused two-week sprints when the spec, plan, implementation, and review loop is running well.

More importantly, I can work on multiple projects in parallel. I do not need to personally write every line of code anymore. I improve the specs, verify the results, improve the feedback loops, and improve the skills. That improves the AI system, and the better AI system improves delivery again.

That is the compounding effect.

This is why I think judging AI only by today's visible failures is strategically wrong.

The model you use today was trained, tested, packaged, and shipped before today. The tools around it were designed before today's workflows became obvious. Compare AI-assisted development one year ago with what is possible now, then imagine the next 3, 6, or 12 months.

That matters because the product you start building today will go live in the future, not in the world you planned it in. By the time it reaches users, the market, tooling, model capabilities, and expectations around AI-assisted delivery may already have moved.

So the pressure is not only to deliver faster. The pressure is to deliver faster while improving quality.

Spec-driven development is the workflow that makes that possible for me: move faster, keep the source of truth clear, automate more quality control, and improve the AI system while the product evolves.

Teams that only ask whether today's AI can replace yesterday's workflow are already late.

So here is the mindset shift I would leave you with.

Whenever you catch yourself doing manual work, ask why this specific work is still manual.

What outcome is it supposed to create? What judgment, context, evidence, or constraint is hidden inside it? Why can AI not do it on your behalf yet? What would AI need to know, check, or prove to take it over safely? And what can you do now to make that possible next time?

That is the real work: turning repeated human effort into explicit knowledge, reusable instructions, review gates, and automated feedback loops.

Bad specs are bureaucracy.

Good specs are leverage.

And if we want AI agents to do more real engineering work, we need to become much better at giving them the kind of work they can actually do well.

If this way of working resonates with you, I also maintain the skills I use for spec-driven AI development:

AI Skills repository: https://github.com/sebastianwessel/skills
My website: https://sebastianwessel.de

The skills cover the workflow I described in this article: spec creation, implementation planning, scoped ticket implementation, and review against the approved spec.

I write about enterprise software, AI-assisted delivery, open source, and the shift from manual coding to improving the systems that guide AI agents.

Conclusion on using a QuickJS sandbox

Sebastian Wessel — Sun, 07 Jul 2024 13:24:06 +0000

Creating the QuickJS package has been a journey in addressing real needs I've encountered in my development career, especially as AI and LLMs become more prevalent in our workflows. It's designed to empower developers to push the boundaries of what's possible in JavaScript applications without compromising on security or code quality.

Whether you're building a complex web application, a desktop app, an AI-powered coding platform, or simply need a safe space to run and test untrusted scripts with Node.js-like capabilities, I believe this package offers the tools you need to execute JavaScript with confidence.

I encourage you to give the QuickJS package a try in your next project, especially if you're working with AI and LLMs. Experience the peace of mind that comes with secure code execution, coupled with the convenience of Node.js module support and robust testing capabilities.

As we continue to explore the frontiers of AI and secure code execution, the QuickJS package stands ready to support your innovative projects. I'm always open to feedback and suggestions from fellow developers. Let's make secure JavaScript execution easier and more accessible together, paving the way for the next generation of AI-powered applications!

Documentation: https://sebastianwessel.github.io/quickjs/
GitHub Repository: https://github.com/sebastianwessel/quickjs
Submit Feedback: Create an Issue on GitHub

Running Tests Inside QuickJS with TestRunner

Sebastian Wessel — Sun, 07 Jul 2024 13:23:56 +0000

The TestRunner is a lightweight testing library that allows you to write and run tests for JavaScript code with ease. It provides a simple interface for defining test suites, tests, and hooks with support for asynchronous code and configurable timeouts. The library also includes Chai's expect function for assertions.

Benefits of Running Tests in a Sandbox

Running tests in a sandbox environment like QuickJS provides several benefits:

Isolation: Each test runs in a separate environment, ensuring no side effects between tests.
Security: A sandboxed environment limits the potential for malicious code to affect the host system.
Consistency: Ensures that tests are run in a controlled environment, leading to more consistent and reliable results.

Importing the Library

To use the TestRunner library in your tests, you need to import it. You also need to ensure that the result of runTests is exported.

import 'testRunner'

Writing Tests

Developers should feel comfortable using the TestRunner as it follows the general approach used in the JavaScript testing ecosystem, similar to Mocha or Jasmine.

Defining a Test Suite

A test suite is defined using the describe function. Inside a test suite, you can define multiple tests using the it function.

describe('Sample Test Suite', () => {
  it('should pass this test', () => {
    expect(true).to.be.true;
  });

  it('should fail this test', () => {
    expect(false).to.be.true;
  });
});

Using Hooks

Hooks are functions that run before or after tests in a suite. The available hooks are:

beforeAll: Runs once before all tests in the suite.
afterAll: Runs once after all tests in the suite.
beforeEach: Runs before each test in the suite.
afterEach: Runs after each test in the suite.

describe('Test Suite with Hooks', () => {
  beforeAll(() => {
    console.log('Running beforeAll hook');
  });

  afterAll(() => {
    console.log('Running afterAll hook');
  });

  beforeEach(() => {
    console.log('Running beforeEach hook');
  });

  afterEach(() => {
    console.log('Running afterEach hook');
  });

  it('should pass this test', () => {
    expect(true).to.be.true;
  });
});

Asynchronous Tests and Hooks

The TestRunner supports asynchronous tests and hooks. Simply return a promise or use async/await in your test or hook functions.

describe('Asynchronous Test Suite', () => {
  beforeAll(async () => {
    await new Promise(resolve => setTimeout(resolve, 1000));
  });

  it('should pass this async test', async () => {
    const result = await new Promise(resolve => setTimeout(() => resolve(true), 1000));
    expect(result).to.be.true;
  });
});

Using Chai's `expect`

The TestRunner includes Chai's expect function for writing assertions in your tests. The expect function is part of Chai's BDD (Behavior-Driven Development) interface. You can learn more about Chai's expect function and its usage at the Chai documentation.

Examples of `expect` Usage

Here are some examples of using Chai's expect function in your tests:

it('should assert true is true', () => {
  expect(true).to.be.true;
});

it('should assert equality', () => {
  expect(1 + 1).to.equal(2);
});

Running Tests

To run the tests, you need to call runTests and export the result. You can specify a custom timeout for tests and hooks by passing the timeout value in milliseconds as an argument to runTests.

import 'testRunner'

describe('Sample Test Suite', () => {
  it('should pass this test', () => {
    expect(true).to.be.true;
  });

  it('should fail this test', () => {
    expect(false).to.be.true;
  });
});

export default await runTests();

Custom Timeout

You can set a custom timeout for all tests and hooks in the suite by passing the timeout value to runTests.

import 'testRunner'

describe('Sample Test Suite with Custom Timeout', () => {
  it('should pass this test', () => {
    expect(true).to.be.true;
  });

  it('should fail this test', () => {
    expect(false).to.be.true;
  });
});

export default await runTests(10000); // Set timeout to 10 seconds

Example Usage

Here is an example demonstrating the complete setup and usage of the TestRunner library.

import 'testRunner'

describe('Example Test Suite', () => {
  beforeAll(() => {
    console.log('Running global beforeAll hook');
  });

  afterAll(() => {
    console.log('Running global afterAll hook');
  });

  beforeEach(() => {
    console.log('Running global beforeEach hook');
  });

  afterEach(() => {
    console.log('Running global afterEach hook');
  });

  describe('Nested Suite', () => {
    beforeAll(() => {
      console.log('Running nested beforeAll hook');
    });

    it('should pass this test', () => {
      expect(true).to.be.true;
    });

    it('should fail this test', () => {
      expect(false).to.be.true;
    });
  });

  it('should pass this test outside nested suite', () => {
    expect(1 + 1).to.equal(2);
  });
});

export default await runTests();

Conclusion

The TestRunner library provides a straightforward way to define and run tests for your JavaScript code. With support for asynchronous operations, configurable timeouts, and Chai's expect function for assertions, you can ensure that your tests are robust and reliable. Happy testing!

Documentation: https://sebastianwessel.github.io/quickjs/
GitHub Repository: https://github.com/sebastianwessel/quickjs
Submit Feedback: Create an Issue on GitHub

Secure Data Transformation in ETL Pipelines

Sebastian Wessel — Sun, 07 Jul 2024 13:23:46 +0000

One particularly powerful use case for the QuickJS package is in the realm of data pipelines and ETL (Extract, Transform, Load) processes.

Imagine a scenario where you're building a flexible data transformation service. Your platform needs to handle incoming data and transform it into a specific format, but here's the catch: the transformation logic is provided by the users themselves in the form of custom JavaScript code.

This presents a significant challenge. On one hand, you want to offer users the flexibility to define their own transformation logic. On the other hand, you need to ensure that this user-provided code doesn't compromise the security or integrity of your system. This is where the QuickJS package truly shines.

Here's how you might implement such a system:

import { quickJS } from '@sebastianwessel/quickjs'

async function setupTransformationEnvironment() {
  const { createRuntime } = await quickJS()
  return createRuntime({
    allowFetch: false,  // Disable network access for security
    allowFs: false,     // Disable file system access
    env: {
      VERSION: '1.0',
      // Add any other environment variables needed for transformation
    },
  })
}

async function transformData(inputData, transformationCode) {
  const runtime = await setupTransformationEnvironment()
  const { evalCode } = runtime

  const wrappedCode = `
    const transform = (data) => {
      ${transformationCode}
    };
    export default transform(${JSON.stringify(inputData)});
  `

  try {
    const result = await evalCode(wrappedCode)
    return { success: true, transformedData: result }
  } catch (error) {
    return { success: false, error: error.message }
  }
}

// Example usage
const inputData = { name: "John Doe", age: 30, city: "New York" }
const userProvidedTransformationCode = `
  // User-defined transformation logic
  return {
    fullName: data.name,
    isAdult: data.age >= 18,
    location: data.city.toUpperCase()
  };
`

const result = await transformData(inputData, userProvidedTransformationCode)
console.log(result)

In this example:

We set up a secure runtime environment using QuickJS, disabling potentially dangerous features like network and file system access.
The transformData function takes input data and user-provided transformation code as parameters.
We wrap the user's code in a function and pass the input data to it.
The code is executed in the sandboxed environment, ensuring that it can't affect the rest of your system.
The transformed data is returned, or an error is caught and reported if the transformation fails.

This approach offers several benefits:

Security: User-provided code runs in a sandbox, protecting your system from malicious or poorly written scripts.
Flexibility: Users can define complex transformation logic tailored to their specific needs.
Control: You can precisely limit what the transformation code can do (e.g., no network requests, no file system access).
Error Handling: Errors in user code are caught and handled gracefully, preventing them from crashing your service.

By leveraging the QuickJS package in this way, you can build a robust, flexible, and secure data transformation service. This pattern can be extended to various other scenarios where you need to run user-provided code safely, such as custom report generation, dynamic data analysis, or even building a secure coding playground for educational purposes.

The ability to execute arbitrary JavaScript securely opens up a world of possibilities for building flexible, user-customizable systems without compromising on security. Whether you're dealing with ETL processes, building a low-code platform, or creating any system that needs to safely execute user-defined logic, the QuickJS package provides the tools you need to do so with confidence.

Documentation: https://sebastianwessel.github.io/quickjs/
GitHub Repository: https://github.com/sebastianwessel/quickjs
Submit Feedback: Create an Issue on GitHub

Empowering AI: The QuickJS Package for LLM Tool Calling

Sebastian Wessel — Sun, 07 Jul 2024 13:23:36 +0000

As AI continues to evolve, the ability to safely execute code becomes increasingly important. The QuickJS package is perfectly positioned to fill this gap, offering a powerful solution for implementing tool calling capabilities in AI applications.

Why QuickJS for AI Tool Calling?

When developing AI systems that interact with user-provided or dynamically generated code, security is paramount. The QuickJS package provides a secure sandbox that allows LLMs to execute JavaScript code safely, opening up a world of possibilities for AI-powered tools and applications.

Key Benefits for AI Developers:

Secure Execution: Run AI-generated or user-provided JavaScript code without risking your main application or server.
Flexible Integration: Easily integrate with various LLM frameworks and AI platforms.
Rich Environment: Provide a Node.js-like environment for more complex tool implementations.
Performance: Leverage the speed of QuickJS for quick code execution in AI workflows.
Customizable Sandbox: Control what capabilities are available to the AI, ensuring safe and appropriate tool use.

Example: Implementing an AI Code Executor with LangChain

Here's an example of how you can use the QuickJS package with LangChain to create a powerful AI code execution tool:

import { ChatOpenAI } from "@langchain/openai";
import { DynamicStructuredTool } from "@langchain/core/tools";
import { quickJS } from '@sebastianwessel/quickjs';
import { z } from "zod";

// Initialize QuickJS (this should be done once)
const initQuickJS = async () => {
  const { createRuntime } = await quickJS();
  return createRuntime({
    allowFetch: false,  // Disable network access for safety
    allowFs: true,      // Allow file system operations if needed
    env: {
      AI_VERSION: '1.0',
    },
  });
};

// Create a QuickJS runtime
const quickJSRuntime = await initQuickJS();

// Define the schema for our JavaScript execution tool
const jsExecutionSchema = z.object({
  code: z.string().describe("The JavaScript code to execute"),
});

// Create the JavaScript execution tool
const jsExecutionTool = new DynamicStructuredTool({
  name: "javascript_executor",
  description: "Executes JavaScript code and returns the result.",
  schema: jsExecutionSchema,
  func: async ({ code }) => {
    try {
      const { evalCode } = await quickJSRuntime;
      const result = await evalCode(code);
      return JSON.stringify(result);
    } catch (error) {
      return `Error executing code: ${error.message}`;
    }
  },
});

// Initialize the language model with the tool
const model = new ChatOpenAI({
  modelName: "gpt-3.5-turbo",
  temperature: 0,
});
const llmWithTools = model.bind({
  tools: [jsExecutionTool],
});

// Example usage
const query = "Calculate the 10th Fibonacci number using JavaScript.";
const result = await llmWithTools.invoke(query);

console.log("AI Response:", result.content);
console.log("Tool Calls:", result.additional_kwargs.tool_calls);

// If there's a tool call, we can execute it
if (result.additional_kwargs.tool_calls) {
  const toolCall = result.additional_kwargs.tool_calls[0];
  const toolResult = await jsExecutionTool.call(
    JSON.parse(toolCall.function.arguments)
  );
  console.log("Tool Execution Result:", toolResult);
}

This setup allows the AI to write and execute JavaScript code safely within the QuickJS sandbox, providing a powerful and flexible tool for various tasks. It combines the strengths of LangChain for AI interactions with the security and flexibility of the QuickJS package for code execution.

Enhancing AI Capabilities

By integrating the QuickJS package into your AI toolkit, you can:

Implement Complex Tools: Allow your AI to write and execute more sophisticated tools on the fly.
Safe Code Testing: Let AI assistants test and debug code in a controlled environment.
Dynamic Data Processing: Enable AI to process data using custom JavaScript functions.
Interactive Coding Tutorials: Create AI-powered coding education platforms with live code execution.
Secure Serverless Functions: Implement AI-generated serverless functions with built-in security.

Documentation: https://sebastianwessel.github.io/quickjs/
GitHub Repository: https://github.com/sebastianwessel/quickjs
Submit Feedback: Create an Issue on GitHub

Execute JavaScript in a WebAssembly QuickJS Sandbox

Sebastian Wessel — Sun, 07 Jul 2024 13:23:22 +0000

Typescript QuickJS Package: Empowering Secure JavaScript Execution in AI and Beyond

As an experienced developer who understands the needs of the community, I've created the QuickJS package to address a critical challenge in modern software development: executing JavaScript securely while maintaining flexibility and performance across various platforms. This TypeScript library offers a robust solution for running JavaScript code in a secure sandbox environment, with particular benefits for AI and large language model (LLM) applications.

The Genesis of the QuickJS Package

My journey began with QuickJS, an impressive small and efficient JavaScript engine originally written in C by Fabrice Bellard and Charlie Gordon. While QuickJS itself is a C program, I saw an opportunity to make it more accessible to the JavaScript and TypeScript community.

The foundation of my package is built upon the excellent work done by the quickjs-emscripten project (https://github.com/justjake/quickjs-emscripten). They've done the crucial work of compiling QuickJS to WebAssembly, enabling its use in web and Node.js environments. What I've created is a high-level abstraction layer around this WebAssembly implementation, designed with developer experience in mind.

A Sandbox Built for Developers, by a Developer

As someone who's been in the trenches of software development, I understand the importance of a tool that's not only powerful but also easy to use. The QuickJS package creates an isolated environment where untrusted code can run freely, separated from your main application, whether it's running in a browser or on a server.

Features Designed with You in Mind

When developing this package, I focused on bringing together features that I, as a developer, would want:

Node-like Module Support: I've included support for core modules similar to Node.js, including node:fs, node:assert, node:util, and node:path.
Fetch API: Because making HTTP requests is such a common need, I've made sure fetch is available within the sandbox.
Custom Module Support: Knowing that every project has unique needs, I've made it possible to use your own modules.
Virtual File System: This allows for file operations without risking your actual file system - a must-have for secure environments.
TypeScript Compatibility: As a TypeScript enthusiast, ensuring seamless integration with TypeScript projects was a priority.
User-Friendly API: I've put a lot of effort into making the API intuitive and easy to use.
Integrated TestRunner: Testing is crucial, so I've included a lightweight testing library right in the sandbox.

The QuickJS Package in Action

Here's a quick example of how you can use the package:

import { quickJS } from '@sebastianwessel/quickjs'

// General setup - do this once
const { createRuntime } = await quickJS()

// Create a runtime instance for code execution
const { evalCode } = await createRuntime({
  allowFetch: true,
  allowFs: true,
  env: {
    MY_ENV_VAR: 'env var value'
  },
})

// Execute code in the sandbox
const result = await evalCode(`
  import { join } from 'node:path'
  import { writeFileSync, readFileSync } from 'node:fs'
  import assert from 'node:assert'

  const fn = async () => {
    console.log(join('src','dist'))
    console.log(env.MY_ENV_VAR)

    // Using node:fs
    writeFileSync('/test.txt', 'Hello, QuickJS!')
    const content = readFileSync('/test.txt', 'utf8')
    assert.strictEqual(content, 'Hello, QuickJS!')

    // Using fetch
    const url = new URL('https://example.com')
    const f = await fetch(url)
    return f.text()
  }

  export default await fn()
`)

console.log(result)

Leveraging Modern Tools for a Better Developer Experience

In developing this package, I've leveraged some of the most exciting tools in the JavaScript ecosystem:

Bun: This all-in-one JavaScript runtime has been instrumental in the development process, offering speed and simplicity.
Hono: For handling HTTP requests, Hono has been a game-changer with its lightweight and performant approach.
Biome: This toolchain has helped maintain code quality and consistency throughout the project.

I've also used other modern tools like poolifier-web-worker for efficient multithreading, tshy for TypeScript package building, and autocannon for performance testing.

Real-World Applications

From my experience, I've seen this package shine in various scenarios:

Running user-provided scripts safely in web or desktop applications
Executing plugins or extensions securely
Creating sandboxed environments for coding challenges or educational platforms
Testing potentially unsafe code snippets in development environments
Implementing secure scripting capabilities in backend services
Powering AI-driven code generation and execution in LLM applications

Performance and Security: No Compromises

As a developer, I know the importance of both performance and security. That's why I've ensured that this package, leveraging the lightweight QuickJS engine compiled to WebAssembly, offers excellent performance without sacrificing security.

Getting Started

I've made sure that getting started with the QuickJS package is straightforward:

npm install @sebastianwessel/quickjs

For more detailed documentation and examples, check out the official documentation and the example repository.

Documentation: https://sebastianwessel.github.io/quickjs/
GitHub Repository: https://github.com/sebastianwessel/quickjs
Submit Feedback: Create an Issue on GitHub

How to Design a SurrealDB schema and create a basic client for TypeScript

Sebastian Wessel — Sun, 17 Sep 2023 13:04:15 +0000

In the midst of a dynamic landscape of exciting new projects, one name shines bright — SurrealDB.

It's not just another database - it's touted as 'The ultimate multi-model database.'.
Just last week, during the 'SurrealDB World' event, they celebrated the launch of their first production-ready version.

What makes SurrealDB unique is its exceptional flexibility in data storage.
Unlike traditional databases that force you to choose between fixed schemas or total chaos, SurrealDB lets you have the best of both worlds.
You can define a table as schema-less while still specifying schema information for known fields.
In this article, we'll explore SurrealDB's features and learn how to create a data schema and a basic client to make the most of this versatile database.

Defining Your Schema

When it comes to creating a schema definition, you have two primary methods at your disposal.

Using SurrealQL for Schema Definition

If you're already familiar with SQL, you'll find SurrealQL to be quite approachable since it shares similarities with standard SQL.

As described in the SurrealDB documentation, you can define your schema like this:

-- Let's start by creating a schema-full user table.
DEFINE TABLE user SCHEMAFULL;

-- Now, let's define some fields.
DEFINE FIELD firstName ON TABLE user TYPE string;
DEFINE FIELD lastName ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string
  ASSERT string::is::email($value);

With SurrealQL, you can structure your schema just the way you want it, making it a powerful tool for designing your data model.

As mentioned earlier, the same principles apply when defining a table as SCHEMALESS instead of SCHEMAFULL.

Here's an example in SurrealQL:

-- Let's create a schemaless user table.
DEFINE TABLE user SCHEMALESS;

-- Now, we'll proceed to define some fields.
DEFINE FIELD firstName ON TABLE user TYPE string;
DEFINE FIELD lastName ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string
  ASSERT string::is::email($value);

When it comes to field definition, SurrealQL offers a rich array of features. Some of the key ones include:

Specifying the data type
Setting up validation rules
Defining default values
Applying data transformations
Establishing a list of possible values, similar to enums

For more detailed information, be sure to explore the official documentation.

Leveraging Surrealist.app

When it comes to working with SurrealDB, there's one tool that I wholeheartedly recommend: Surrealist.
This software is a game-changer for simplifying your SurrealDB experience.

Surrealist offers a user-friendly interface that streamlines your interactions with SurrealDB. Not only does it come in a convenient browser version, but it also offers the powerful Surrealist Desktop application.

Surrealist Desktop takes your SurrealDB workflow to the next level by introducing a range of additional features, including the highly versatile Designer.

The Surrealist Designer empowers you to effortlessly craft your table schema and manage entity relations. It's not just for beginners; the intuitive UI makes it accessible to newcomers, while experts can appreciate its ability to visualize even the most intricate data structures.

Whether you're just starting or diving into complex projects, Surrealist is your trusted companion for making the most of SurrealDB. Give it a try and see how it enhances your database design journey.

Generating Zod Schemas and TypeScript Clients from SurrealDB

Being a TypeScript developer, my journey with a database doesn't end at just interacting with it.
Naturally, I want a TypeScript program that seamlessly connects to SurrealDB.

I soon found myself at a point where I wanted to automate the creation of a simple client, leveraging the information already present in the database.

So, I embarked on a weekend coding session and crafted a small CLI tool. This tool works its magic by extracting schema information directly from SurrealDB, and it doesn't stop there. It also generates corresponding Zod schemas and a TypeScript client for basic CRUD operations.
The client is designed to work seamlessly with the official SDK, making the integration process smooth and efficient.

With this tool, I aimed to simplify the process of working with SurrealDB, allowing TypeScript developers to dive into their projects with confidence, knowing they have a solid foundation to build upon.

The intention is, to provide a solid starting point for development, and to speed up the processed.

You can find the project on GitHub:
https://github.com/sebastianwessel/surrealdb-client-generator

You have multiple configuration options at your disposal, which can be set either as command-line interface (CLI) options or within a configuration file.
What's more, you can even use both methods simultaneously.
In such cases, the CLI options take precedence.

Getting started with the tool is a breeze:

npx surql-gen

Options:
  -V, --version                          output the version number
  -f, --file [schemaFile]                a SurrealQL file containing the definitions (default: "myschema.surql")
  -c, --config [configFile]              SurrealDB connection url (default: "surql-gen.json")
  -s, --surreal [surreal]                SurrealDB connection url (default: "ws://127.0.0.1:8000")
  -u, --username [username]              auth username (default: "root")
  -p, --password [password]              auth password (default: "root")
  -n, --ns [ns]                          the namspace (default: "test")
  -d, --db [db]                          the database (default: "test")
  -o, --outputFolder [outputFolder]      output folder (default: "client_generated")
  -g, --generateClient [generateClient]  generate client (default: true)

For further information, just check out the readme file in the repository.

Understanding Generated Files

In your designated output folder, it's essential to grasp how the generated files are organized for efficient management:

`_generated` Subfolder

Anything residing beneath the _generated subfolder is subject to potential overwriting during subsequent runs of the generator. This serves as the workspace where dynamic updates can occur.

`schema` Subfolder

The schema subfolder plays a pivotal role. It contains the schema and type definitions, offering customization possibilities. Unlike the _generated folder, everything within schema is generated only once and remains untouched or deleted in subsequent runs of the generator.

`client` Subfolder

When it comes to accessing the generated client code, you'll find it neatly tucked away within the client subfolder.

This organized structure ensures that your generated files are readily accessible while maintaining the integrity of your project's foundation.

Using the Client

The generated client is designed with simplicity in mind, adhering to the efficient repository pattern. In this pattern, each table is treated as a distinct entity, complete with its dedicated repository. These repositories, in turn, consolidate actions specific to the respective entity.

Using the client is straightforward and user-friendly. You'll always encounter methods in the format of get[Entity Name]Repository(db: Surreal), requiring only the database instance as an argument.

For a quick illustration, let's take a peek at how we can access all the generated methods for a project entity:

import { Surreal } from 'surrealdb.js'

import { getProjectRepository } from './client_generated/client/project/getProjectRepository.js'

const main = async () => {
  const db = new Surreal()
  await db.connect('ws://0.0.0.0:8000', {
    auth: { user: 'root', pass: 'root' },
  })
  await db.use({
    ns: 'voyage',
    db: 'voyage',
  })

  const rep = getProjectRepository(db)

  const project = await rep.createProject({
    name: 'Test project',
    logo: '/mylogo',
  })
  console.log('project', project)

  const projects = await rep.getAllProjects()
  console.log('projects', projects)

  const updated = await rep.updateProject(project.id, { name: 'Renamed !' })
  console.log('updated', updated)

  const selected = await rep.getProjectById(project.id)
  console.log('selected', selected)

  await rep.deleteProject(project.id)
  console.log('deleted')

  const projectsDel = await rep.getAllProjects()
  console.log('projects', projectsDel)

  await db.close()
}

main()

All return values are automatically typed based on the Zod schema, simplifying your code and ensuring consistency.
Even if you customize a schema, TypeScript types adapt seamlessly, eliminating the need for manual updates.
This streamlined process keeps your codebase error-free and agile, saving you time and effort.

Alternative

There is the possibility, to disable the generation of the TypeScript client.
The intention is, to only generate Zod schema, which than can simply used in Cirql - SurrealDB ORM & Query Builder or in your own choice.

Final words

In Closing

SurrealDB is undeniably a remarkable addition to the world of databases, and it's a platform that deserves your attention. With Surrealist, the entry barrier for beginners is lowered to a minimum, offering a professional UI enriched with fantastic features.

I trust that my small tool will serve as a valuable resource for TypeScript developers looking to dive into the world of SurrealDB, making it more accessible and enjoyable.

If you find this tool helpful, I kindly ask you to show your appreciation by giving it a star on GitHub.

And, of course, if you encounter any issues or have suggestions for improvements, please don't hesitate to open an issue on GitHub. Your feedback is invaluable.

For further inquiries about SurrealDB, don't hesitate to explore their comprehensive documentation or engage with the community on their Discord channel.

Happy coding - Cheers and bye bye! 👋

Looking to dive deeper into SurrealDB?
Don't miss out on the comprehensive series I've recently penned

Sebastian Wessel

Sep 8 '23

SurrealDB - The Magic Database to Keep on Your Radar

#news #database #programming #tutorial

Comments

3 min read

PURISTA - Tests with Jest, Sinon.js and Testcontainers

Sebastian Wessel — Tue, 12 Sep 2023 08:48:46 +0000

In the journey of crafting the PURISTA TypeScript backend framework, the need for automated software testing became increasingly apparent.
PURISTA's extensive amount of adapters and integrations with third-party solutions makes it impractical to conduct manual testing repeatedly.
In this article, we dive into the pivotal role of automated testing in ensuring the reliability and stability of PURISTA's offerings.

Moreover, enabling developers to effortlessly test their code built on top of PURISTA stands as a pivotal aspect of the framework.

Jest

Jest offers a comprehensive test suite where you can efficiently organize, implement, and execute your tests. With approximately 1490 contributors, Jest has played a pivotal role in simplifying the process of writing tests, as demonstrated below:

import { asyncOperation, syncOperation } mytestfile.test.js

describe('My testfile works', ()=>{
  it('is exected to be ok', () => {
    const result = syncOperation()
    expect(result).toBe('OK')
  })

  it('works with async await', async ()=>{
    const result = asyncOperation()
    await expect(result).resolves.toBe('OK')
  })
})

As the number on GitHub shows: This awesome tool is used by 10.4 millions!
This unbelievable number shows, how important it is.

A massive shout-out to Jest and all its dedicated contributors! Consider starring it on GitHub, giving a shout-out on social media, or mentioning it in your readme file to show your appreciation. 🌟👏

We use Jest together with @swc/jest, which speeds up our test runs dramatically.
They don't lie with "Super-fast alternative for babel-jest or ts-jest without type checking".
It's the second great tool by Vercel we use at PURISTA.

Sinon.js

When writing tests, you probably will come to the point where you need to mock, fake or spy on something. Even if the test framework is providing some helpers for it, you should have a look at Sinon.js.

At PURISTA, we primarily leverage Sinon.js to deliver a seamless testing experience for developers.
We provide for example the getLoggerMock function, which returns an easy way to test logging, without poluting the test runner output.

This function looks like this:

export const getLoggerMock = (sandbox?: SinonSandbox) => {
  const info = sandbox?.stub() || stub()
  const error = sandbox?.stub() || stub()
  const warn = sandbox?.stub() || stub()
  const debug = sandbox?.stub() || stub()
  const trace = sandbox?.stub() || stub()
  const fatal = sandbox?.stub() || stub()

  const mock: Logger = {
    info,
    error,
    warn,
    debug,
    trace,
    fatal,
    getChildLogger: () => mock,
  }

  return {
    stubs: {
      info,
      error,
      warn,
      debug,
      trace,
      fatal,
    },
    mock,
  }
}

As you can see, we've created stubs, which are a form of mock implementations. You can use them to check whether a stub is called, how many times it's called, if it's called with specific parameters, and more. Additionally, Sinon.js offers sandboxing, a highly recommended feature. It prevents your tests from interfering with each other, ensuring clean and reliable results.

As an example on how it might look:

import { Logger } from '@purista/core'
import { createSandbox } from 'sinon'

function syncOperation(logger: Logger) {
   logger.info('info log')
   return 'OK'
}

describe('My testfile works', ()=>{
  const sandbox = createSandbox()

  afterEach(() => {
    sandbox.reset()
  })

  it('is exected to be ok', () => {
    const loggerMock = getLoggerMock()

    const result = syncOperation(loggerMock.mock)
    expect(result).toBe('OK')
    expect(loggerMock.stub.info.calledOnceWith('info log')).toBeTruthy()
  })

})

Sinon.js is unbelievably helpful, and the 328 contributors are doing an incredible job. It's no surprise that Sinon.js is trusted by over 574k developers. Show them some love with a big shout-out and a star on GitHub!

If you haven't used Sinon.js before, it's definitely worth giving it a try.

Testcontainers

To be honest, Testcontainers wasn't on our radar initially.
However, we soon realized the need for a viable solution to conduct integration tests for:

Testcontainers was the gamechanger here.
It is super easy to spin up a docker container and run tests against a real running system.

To show you, how simple it is:

Here is the example, on how start a full RabbitMQ before we run our tests:

import { GenericContainer, StartedTestContainer } from 'testcontainers'

const AMQP_PORT = 5672

describe('@purista/amqpbridge', () => {
  let container: StartedTestContainer

  beforeAll(async () => {
    container = await new GenericContainer('rabbitmq:alpine')
      .withExposedPorts({ host: AMQP_PORT, container: AMQP_PORT })
      .start()
  })

  afterAll(async () => {
    await container.stop()
  })

It significantly enhanced our local testing process. Furthermore, Testcontainers is a versatile tool available for multiple programming languages.

A heartfelt thank you to all the contributors of Testcontainers for this incredible project! We deeply appreciate the outstanding work you've put into it.

If you're searching for content ideas for the next article, consider crafting a cool piece about Testcontainers and its practical applications. Dive into how to harness its power effectively.

Now that we've explored the powerful tooling required to build PURISTA itself, let's shift our focus to the components under the hood that make PURISTA tick.

Be sure to check out the upcoming article in this series!

PURISTA: Build with rimraf, esbuild, Turbo & git-cliff

Sebastian Wessel — Mon, 11 Sep 2023 21:15:26 +0000

In our previous article, we laid the foundation with a glimpse of our coding setup.

It's now time to spotlight the indispensable build tools that power its development.

rimraf

Huge thanks to Isaacs!
Rimraf comes to the rescue, providing a reliable solution for deep, recursive removal of folders and files.
At PURISTA, we rely on rimraf to maintain pristine build output directories.

Turbo

PURISTA is organized in a monorepo.
During the development and build process, Turbo is used to execute different tasks and steps on multiple packages with one command.

We aren't harnessing the full potential and capabilities of Turbo at the moment since PURISTA currently requires only a few straightforward build tasks.

If you have more complex tasks, especially those with interdependencies between steps, it's worth exploring https://turbo.build

Esbuild

In its early stages, PURISTA was built using the standard TypeScript compiler.
However, this approach excelled in creating CommonJS packages but turned into a nightmare when it came to generating ESM builds.

esbuild - the rescue!
No longer struggling with configs, file extensions or similar.

With esbuild, it was becoming simple and fast.

We created a small script:

const esbuild = require('esbuild')

esbuild
  .build({
    entryPoints: ['./src/index.ts'],
    outfile: './lib/esm/index.mjs',
    bundle: true,
    format: 'esm',
    splitting: false,
    platform: 'node',
    sourcemap: false,
    target: 'node18',
    minify: true,
    packages: 'external',
  })
  .catch(() => process.exit(1))

esbuild
  .build({
    entryPoints: ['./src/index.ts'],
    outfile: './lib/cjs/index.cjs',
    bundle: true,
    format: 'cjs',
    splitting: false,
    platform: 'node',
    sourcemap: false,
    target: 'node18',
    minify: true,
    packages: 'external',
  })
  .catch(() => process.exit(1))

Since this approach only generates JavaScript files, and we aim to provide proper TypeScript types to PURISTA users, we utilize the TypeScript compiler specifically for building types.

tsc --emitDeclarationOnly --declarationMap false --declaration --outDir lib/types

In package.json, only these additions were necessary:

{
  "directories": {
      "lib": "lib/index.js"
  },
  "main": "./lib/cjs/index.cjs",
  "module": "./lib/esm/index.mjs",
  "exports": {
      ".": {
          "import": "./lib/esm/index.mjs",
          "require": "./lib/cjs/index.cjs",
          "types": "./lib/types/index.d.ts"
      }
  },
  "typings": "lib/types/index.d.ts",
  "files": [
      "lib"
  ]
}

A big thank you ❤️ to all contributors and maintainers of esbuild!
It solved the issue with CommonJS/ESM for us and produces size optimized outputs for all PURISTA packages.

git-cliff

Changelogs are nice and everybody likes them, but nobody wants to maintain them 😜.
Here, git-cliff by Orhun Parmaksız is one simple to use solution.

One simple command:

git-cliff > CHANGELOG.md

And your changelog gets generated from your git history.

Undoubtedly one of the time-saving tools, you should check out at https://git-cliff.org

In the upcoming article of this series, we will delve deeper into the test setup. Stay tuned!

PURISTA - Thanks to amazing open-source software

Sebastian Wessel — Mon, 11 Sep 2023 20:17:57 +0000

Welcome to our series on the unsung heroes behind PURISTA!

Ever wondered about PURISTA?
It's not just another Typescript backend framework for simply building HTTP-endpoints.
It's a versatile solution that embraces diverse techniques for highly distributed deployments, taking inspiration from event-driven architecture.
If you're interested, you're invited to take a look at the official website http://purista.dev.

But hold on, this series isn't about the framework itself. Instead, we're here to shine a spotlight on the incredible libraries, tools, software, and passionate contributors that make PURISTA possible.

In this series, we will introduce all the tools, explain how we use them, why we find them essential, and endeavor to illustrate why they might also be a suitable solution for you.

General setup

Most developers should be more or less familiar with the basic setup.

VSCode as a code editor with ESLint plugin.

GitHub is uses as repository, issue & project tracker, and also for hosting the official website.

Coding Setup

In addition to Node.js and TypeScript, we rely on two indispensable tools available as npm modules:

ESLint and Prettier

Maintaining a clean, readable, and consistent codebase is essential, and ESLint and Prettier are the perfect tools for the job.
Just enable "lint on save" in VSCode, and you won't have to worry about it. They're a "must-have," even for small personal projects.

See https://eslint.org and https://prettier.io

ESLint is extended by some awesome plugins and extensions:

eslint-plugin-simple-import-sort by Simon Lydell @SimonLydell
eslint-plugin-node by Toru Nagashima - Dev.to: @mysticatea & Twitter: @mysticatea
eslint-plugin-json by Azeem Bande-Ali
eslint-plugin-import
eslint-config-standard

In our upcoming article, we'll delve deep into the inner workings of PURISTA's build pipeline. Stay tuned for an in-depth exploration!

SurrealDB - Improve data integrity by adding schema information

Sebastian Wessel — Fri, 08 Sep 2023 20:46:26 +0000

In the concluding chapter of this series, we'll delve into the intriguing world of SurrealDB's schema possibilities and explore how they can elevate our data integrity to new heights.

You can define fields for tables. We will take the user table as an example here.

Our initial definition was:

-- Define the user table
DEFINE TABLE user SCHEMALESS;

We will add now some field definitions:

-- Define the user table
DEFINE TABLE user SCHEMALESS;
DEFINE FIELD name ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string;
DEFINE FIELD firstName ON TABLE user TYPE string;
DEFINE FIELD lastName ON TABLE user TYPE string;
DEFINE FIELD createdAt ON TABLE user TYPE datetime;

We're on the right track so far. We've defined the necessary fields, and we've also specified their types.
But there are some improvements, we can make.

Now, let's focus on the createdAt attribute. In this case, we should establish a default value that automatically captures the creation timestamp when the entity is generated.

DEFINE FIELD createdAt ON TABLE user TYPE datetime DEFAULT time::now();

We should also enhance the email field.
There are two improvements we can make.
First, we should specify the field type as more than just a generic string, as we know it must adhere to the email pattern.

DEFINE FIELD email ON TABLE user TYPE string ASSERT string::is::email($value);

Secondly, we want to ensure, that the email is globally unique. To ensure this, we define a unique index.

DEFINE INDEX uniqueEmailIndex ON TABLE user COLUMNS email UNIQUE;

Here's our ultimate definition for our user table:

-- Define the user table
DEFINE TABLE user SCHEMALESS;
DEFINE FIELD name ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string ASSERT string::is::email($value);
DEFINE FIELD firstName ON TABLE user TYPE string;
DEFINE FIELD lastName ON TABLE user TYPE string;
DEFINE FIELD createdAt ON TABLE user TYPE datetime DEFAULT time::now();

DEFINE INDEX uniqueEmailIndex ON TABLE user COLUMNS email UNIQUE;

Concerning the relationships we've established between various entities, it's important to avoid duplicates between the same entities.
In this context, we can create a unique index to prevent multiple connections of a specific user to a particular tenant.

-- prevent linking a user to the same tenant multiple times
DEFINE INDEX tenant_memberIndex
    ON TABLE tenant_member
    COLUMNS in, out UNIQUE;

Final thoughts

As we conclude this series, we've only just scratched the surface of SurrealDB's capabilities, with a strong focus on its graph structures.

SurrealDB has an exciting set of features and upcoming announcements that make it a truly fascinating unicorn in the database world.

The handling of unique record-IDs and the possibilities they unlock are nothing short of amazing.
The freedom to choose between a relational database, key-value store, NoSQL/document database, graph database, or specialized time series database while using one database simplifies life significantly.
Tailoring how you store and access data based on your specific needs and mixing things up as required is the way forward.

While SurrealDB is still in its early stages and not officially production-ready, I encourage you to give it a try in one of your upcoming small (or side) projects.

The adventure with SurrealDB may just be the unique and rewarding experience you've been looking for.

SurrealDB - Query and combine data via relations

Sebastian Wessel — Fri, 08 Sep 2023 20:46:15 +0000

In the previous article of this series, we set up the foundation and added some sample data.

Now, we'll dive into retrieving and merging that data.
I strongly encourage you to explore the SurrealDB documentation. It will make understanding the upcoming examples much smoother.

See: SELECT and RELATE

Query tenant(s)

To start, we'll keep it simple and begin by fetching all the tenants.

-- fetch all tenants
SELECT * from tenant;

Result:

[
    {
        "id": "tenant:car",
        "name": "Car Enthusiasts"
    },
    {
        "id": "tenant:cat",
        "name": "Cat Owners"
    },
    {
        "id": "tenant:musician",
        "name": "Musicians"
    }
]

Add available roles

Our next step is to find out which roles are generally accessible within the context of a particular tenant.

This information is stored in the tenant_role relation.
We can now extend our query as shown below.

-- select the tenant car enthusisast
-- fetch the related roles and return it as availableRoles
SELECT *,
  (SELECT * FROM <-tenant_role<-role) as availableRoles
FROM tenant:car;

Result:

[
    {
        "availableRoles": [
            {
                "id": "role:admin",
                "name": "Administrator"
            },
            {
                "id": "role:reader",
                "name": "Content Reader"
            },
            {
                "id": "role:author",
                "name": "Content Author"
            }
        ],
        "id": "tenant:car",
        "name": "Car Enthusiasts"
    }
]

Now, let's tidy up the output. Since we're aware that we're fetching just one tenant, we can use the ONLY statement between FROM and tenant:car to directly obtain a single result object. Additionally, we'll limit the output to only display the role IDs.

-- return only id´s of roles and return as single object
SELECT *,
  (SELECT id FROM <-tenant_role<-role).id as availableRoles 
FROM ONLY tenant:car;

Result:

{
    "availableRoles": [
        "role:admin",
        "role:reader",
        "role:author"
    ],
    "id": "tenant:car",
    "name": "Car Enthusiasts"
}

Add tenant members

In the next step, we will also return the users, which are car enthusiasts.

-- add members of tenant car
SELECT *,
      (SELECT * FROM <-tenant_member<-user) as members,
      (SELECT id FROM <-tenant_role<-role).id as availableRoles 
FROM ONLY tenant:car;

Result:

{
    "availableRoles": [
        "role:admin",
        "role:reader",
        "role:author"
    ],
    "id": "tenant:car",
    "members": [
        {
            "email": "john.doe@example.com",
            "firstName": "John",
            "id": "user:1",
            "lastName": "Doe",
            "name": "John Doe"
        }
    ],
    "name": "Car Enthusiasts"
}

Add tenant member roles

We will now add the role information to each user who is a member of the given tenant.
We will change

(SELECT * FROM <-tenant_member<-user) as members,

(
 SELECT 
  (SELECT * FROM ONLY <-person) as person,
  (SELECT id FROM ->member_role->role).id as roles,
 FROM <-tenant_member
) as members

As you can observe, we've made a change in how we resolve data. Now, we don't go all the way up to the user through <-tenant_member<-user. Instead, we stop at the relation entry itself with <-tenant_member.

Recall our data schema. We've established a relationship between users and tenants. This relationship, in turn, has its own connections to one or even multiple roles.

Think of it as a crossroads. If you head straight ahead, you'll discover user information. But if you veer left or right, you'll stumble upon the roles assigned to that user within a specific tenant.
The full query:

SELECT *, (
      SELECT 
            (SELECT * FROM ONLY <-user) as user,
            (SELECT id FROM ->member_role->role).id as roles
      FROM <-tenant_member
      ) as members,
      (SELECT id FROM <-tenant_role<-role).id as availableRoles 
FROM ONLY tenant:car;

Result:

{
    "availableRoles": [
        "role:admin",
        "role:reader",
        "role:author"
    ],
    "id": "tenant:car",
    "members": [
        {
            "roles": [
                "role:author"
            ],
            "user": {
                "email": "john.doe@example.com",
                "firstName": "John",
                "id": "user:1",
                "lastName": "Doe",
                "name": "John Doe"
            }
        }
    ],
    "name": "Car Enthusiasts"
}

Add tenant permissions for roles of members

In most scenarios, it may not be practical to display the permissions for every user within a tenant at this stage.

However, for the sake of learning and demonstration, I'll illustrate the impressive capabilities of SurrealDB.

We will need to add something like this:

(SELECT * FROM ->member_role->role->role_permission->permission) as permissions

Which will add something like this:

"permissions": [
  {
      "id": "permission:update",
      "name": "update content"
  },
  {
      "id": "permission:read",
      "name": "read content"
  },
  {
      "id": "permission:create",
      "name": "create content"
  }
],

In our example, everything appears neat and straightforward.
However, our user currently has just one role assigned.
When a user holds multiple roles, they might end up with the same permission through different roles. This could lead to duplicate entries in our results.

Fortunately, SurrealDB offers a set of handy helper functions. We'll employ array::group to eliminate these duplicates from our results.

The complete query:

SELECT *, (
      SELECT 
            (SELECT * FROM ONLY <-user) as user,
            (SELECT id FROM ->member_role->role).id as roles,
            array::group((SELECT * FROM ->member_role->role->role_permission->permission)) as permissions
      FROM <-tenant_member
      ) as members,
      (SELECT id FROM <-tenant_role<-role).id as availableRoles 
FROM ONLY tenant:car;

Result:

{
    "availableRoles": [
        "role:admin",
        "role:reader",
        "role:author"
    ],
    "id": "tenant:car",
    "members": [
        {
            "permissions": [
                {
                    "id": "permission:update",
                    "name": "update content"
                },
                {
                    "id": "permission:read",
                    "name": "read content"
                },
                {
                    "id": "permission:create",
                    "name": "create content"
                }
            ],
            "roles": [
                "role:author"
            ],
            "user": {
                "email": "john.doe@example.com",
                "firstName": "John",
                "id": "user:1",
                "lastName": "Doe",
                "name": "John Doe"
            }
        }
    ],
    "name": "Car Enthusiasts"
}

Final query 🎉

Let's remove the permissions and the ONLY Statement.
Our query, for fetching single or multiple tenants, is:

SELECT *, (
      SELECT 
            (SELECT * FROM ONLY <-user) as user,
            (SELECT id FROM ->member_role->role).id as roles
      FROM <-tenant_member
      ) as members,
      (SELECT id FROM <-tenant_role<-role).id as availableRoles 
FROM tenant;

Query user(s)

When we initiate a query for a user, our goal is to retrieve the user's details.

Additionally, we aim to determine which tenants the user belongs to and understand the roles associated with each of these tenant memberships.

We will utilize the same relationships as we did for the tenant query. The only distinction here lies in our approach: we will traverse most of the graph relationships in the reverse direction.
Because of this, I will skip the detailed explanation.

Our user query:

-- query user(s) and return related tenants, roles and permissions

SELECT *, (
      SELECT 
            (SELECT * FROM ONLY ->tenant) as tenant,
            (SELECT id FROM ->member_role->role).id as roles,
            array::group((SELECT * FROM ->member_role->role->role_permission->permission)) as permissions
      FROM ->tenant_member
      ) as tenants
FROM user;

Result:

[
    {
        "email": "john.doe@example.com",
        "firstName": "John",
        "id": "user:1",
        "lastName": "Doe",
        "name": "John Doe",
        "tenants": [
            {
                "permissions": [
                    {
                        "id": "permission:update",
                        "name": "update content"
                    },
                    {
                        "id": "permission:read",
                        "name": "read content"
                    },
                    {
                        "id": "permission:create",
                        "name": "create content"
                    }
                ],
                "roles": [
                    "role:author"
                ],
                "tenant": {
                    "id": "tenant:car",
                    "name": "Car Enthusiasts"
                }
            }
        ]
    }
]

Query information for a specific user within a particular tenant

As an addition to the previous queries, I will provide a query, which you might need in similar way in real world scenarios.

-- query the information for a specific user within a particular tenant and return user information, tenant information, roles and permissions

SELECT
      (SELECT * FROM ONLY <-user) as user,
      (SELECT *, (SELECT id FROM <-tenant_role<-role).id as availableRoles FROM ONLY ->tenant) as tenant,
      (SELECT id FROM ->member_role->role).id as roles,
      array::group((SELECT * FROM ->member_role->role->role_permission->permission)) as permissions
FROM ONLY tenant_member
WHERE in='user:1' and out='tenant:car'

Result:

{
    "permissions": [
        {
            "id": "permission:update",
            "name": "update content"
        },
        {
            "id": "permission:read",
            "name": "read content"
        },
        {
            "id": "permission:create",
            "name": "create content"
        }
    ],
    "roles": [
        "role:author"
    ],
    "tenant": {
        "availableRoles": [
            "role:admin",
            "role:reader",
            "role:author"
        ],
        "id": "tenant:car",
        "name": "Car Enthusiasts"
    },
    "user": {
        "email": "john.doe@example.com",
        "firstName": "John",
        "id": "user:1",
        "lastName": "Doe",
        "name": "John Doe"
    }
}

DEV Community: Sebastian Wessel

How-To Spec-Driven AI Development

What This Covers

The Goal Is Not More Code

AI Can Only Meet Expectations It Can See

Human Language Becomes The Interface

Spec-Driven Development Starts With The Knowns

Human Work Moves Up A Level

Good Specs Make Expectations Executable

Skills Turn Judgment Into Guidance

Writing Specs Is An Iterative Loop

Reviewing Specs Is Also An AI Workflow

Planning Makes Work Delegatable

Implementation Should Not Invent

Review Becomes A Trust Pipeline

What Works For Me

Open Questions To Handle

Conclusion

Conclusion on using a QuickJS sandbox

Running Tests Inside QuickJS with TestRunner

Benefits of Running Tests in a Sandbox

Importing the Library

Writing Tests

Defining a Test Suite

Using Hooks

Asynchronous Tests and Hooks

Using Chai's expect

Examples of expect Usage

Running Tests

Custom Timeout

Example Usage

Conclusion

Secure Data Transformation in ETL Pipelines

Empowering AI: The QuickJS Package for LLM Tool Calling

Why QuickJS for AI Tool Calling?

Key Benefits for AI Developers:

Example: Implementing an AI Code Executor with LangChain

Enhancing AI Capabilities

Execute JavaScript in a WebAssembly QuickJS Sandbox

Typescript QuickJS Package: Empowering Secure JavaScript Execution in AI and Beyond

The Genesis of the QuickJS Package

A Sandbox Built for Developers, by a Developer

Features Designed with You in Mind

The QuickJS Package in Action

Leveraging Modern Tools for a Better Developer Experience

Real-World Applications

Performance and Security: No Compromises

Getting Started

How to Design a SurrealDB schema and create a basic client for TypeScript

Defining Your Schema

Using SurrealQL for Schema Definition

Leveraging Surrealist.app

Generating Zod Schemas and TypeScript Clients from SurrealDB

Understanding Generated Files

_generated Subfolder

schema Subfolder

client Subfolder

Using the Client

Alternative

Final words

In Closing

SurrealDB - The Magic Database to Keep on Your Radar

PURISTA - Tests with Jest, Sinon.js and Testcontainers

Jest

Sinon.js

Testcontainers

PURISTA: Build with rimraf, esbuild, Turbo & git-cliff

rimraf

Turbo

Esbuild

git-cliff

PURISTA - Thanks to amazing open-source software

General setup

Coding Setup

ESLint and Prettier

SurrealDB - Improve data integrity by adding schema information

Final thoughts

SurrealDB - Query and combine data via relations

Query tenant(s)

Add available roles

Using Chai's `expect`

Examples of `expect` Usage

`_generated` Subfolder

`schema` Subfolder

`client` Subfolder