@slopware/sloppy-linux-x64 0.1.0-alpha.0

package/examples/framework-sqlite-crud/app.ts

@@ -0,0 +1,90 @@
+import {
+    Body,
+    Email,
+    NonEmptyString,
+    PositiveInt,
+    RequestContext,
+    Results,
+    Route,
+    Sloppy,
+} from "sloppy";
+import { Sqlite } from "sloppy/providers/sqlite";
+
+type UserCreate = {
+    name: NonEmptyString;
+    email: Email;
+};
+
+type UserDto = {
+    id: number;
+    name: string;
+    email: string;
+};
+
+const app = Sloppy.create();
+
+async function seedUsers(db, ctx) {
+    await db.exec(
+        "create table if not exists users (id integer primary key, name text not null, email text not null unique)",
+        [],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    await db.exec(
+        "insert or ignore into users (id, name, email) values (?, ?, ?)",
+        [1, "Ada Lovelace", "ada@example.test"],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    await db.exec(
+        "insert or ignore into users (id, name, email) values (?, ?, ?)",
+        [2, "Grace Hopper", "grace@example.test"],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+}
+
+app.get("/users", async (db: Sqlite<"main">, ctx: RequestContext) => {
+    await seedUsers(db, ctx);
+    const users = await db.query<UserDto>(
+        "select id, name, email from users order by id",
+        [],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    return Results.ok(users);
+}).withName("Users.List");
+
+app.get("/users/{id:int}", async (
+    id: Route<PositiveInt>,
+    db: Sqlite<"main">,
+    ctx: RequestContext,
+) => {
+    await seedUsers(db, ctx);
+    const user = await db.queryOne<UserDto>(
+        "select id, name, email from users where id = ?",
+        [id],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    return user === null ? Results.notFound() : Results.ok(user);
+}).withName("Users.Get");
+
+app.post("/users", async (
+    input: Body<UserCreate>,
+    db: Sqlite<"main">,
+    ctx: RequestContext,
+) => {
+    await seedUsers(db, ctx);
+    await db.exec(
+        "insert or ignore into users (name, email) values (?, ?)",
+        [input.name, input.email],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    const user = await db.queryOne<UserDto>(
+        "select id, name, email from users where email = ?",
+        [input.email],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    if (user === null) {
+        throw new Error("SQLite user insert did not return a row.");
+    }
+    return Results.created(`/users/${user.id}`, user);
+}).withName("Users.Create");
+
+export default app;

package/examples/framework-sqlite-crud/appsettings.json

@@ -0,0 +1,11 @@
+{
+  "Sloppy": {
+    "Providers": {
+      "sqlite": {
+        "main": {
+          "database": ":memory:"
+        }
+      }
+    }
+  }
+}

package/examples/framework-sqlserver-crud/README.md

@@ -0,0 +1,73 @@
+# Framework SQL Server CRUD Example
+
+## What this shows
+
+A users API backed by SQL Server:
+
+- typed `Body<T>` and `Route<T>` handler parameters;
+- `SqlServer<"main">` typed provider injection;
+- SQL Server parameter placeholders (`?`);
+- `output inserted...` for create responses;
+- request `signal` and `deadline` passed to database calls.
+
+## Requirements
+
+- A V8-enabled `sloppy` runtime.
+- Microsoft ODBC Driver 18 or 17 for SQL Server.
+- A SQL Server test database with a `users` table.
+- `Sloppy__Providers__sqlserver__main__connectionString` set in the environment.
+
+You do not need SQL Server or ODBC for normal Sloppy apps, the Quickstart,
+Program Mode, SQLite, templates, or package support. Sloppy does not bundle
+Microsoft's ODBC driver in the core alpha package; install it from Microsoft's
+platform packages or through your organization's managed deployment.
+
+Example table shape:
+
+```sql
+create table users (
+  id int identity primary key,
+  name nvarchar(200) not null,
+  email nvarchar(320) not null unique
+);
+```
+
+## Run
+
+Set the connection string and run the SQL Server integration checks:
+
+```powershell
+$env:Sloppy__Providers__sqlserver__main__connectionString = "Driver={ODBC Driver 18 for SQL Server};Server=tcp:127.0.0.1,1433;Database=sloppy_test;UID=<user>;PWD=<password>;Encrypt=yes;TrustServerCertificate=yes;"
+.\tools\windows\test-live-sqlserver.ps1
+```
+
+## Expected result
+
+The script runs the SQL Server native and bridge tests selected by:
+
+```powershell
+ctest --test-dir build\windows-relwithdebinfo --output-on-failure -R "data\.sqlserver\.live_provider|conformance\.sqlserver\.(native_live|bridge_live)"
+```
+
+With driver, database, and connection string configured, `GET /users` returns
+JSON rows from SQL Server.
+
+## Files to look at
+
+- `app.ts` — `SqlServer<"main">` injection and SQL Server statements.
+- Generated `.sloppy/app.plan.json` — inferred `sqlserver/main` provider metadata.
+- `docs/api/data.md` — SQL Server setup and unavailable driver cases.
+
+## Scope
+
+Schema setup is manual for this example. It also depends on Microsoft ODBC
+Driver 17 or 18 and available async SQL Server support. Migrations, ORM-style
+modeling, deployment guidance is outside this example, and package dependency
+behavior is covered by the package/dependency examples.
+
+## Related docs
+
+- `docs/api/data.md`
+- `docs/reference/providers.md`
+- `docs/reference/framework.md`
+- `docs/internals/provider-runtime.md`

package/examples/framework-sqlserver-crud/app.ts

@@ -0,0 +1,64 @@
+import {
+    Body,
+    Email,
+    NonEmptyString,
+    PositiveInt,
+    RequestContext,
+    Results,
+    Route,
+    Sloppy,
+} from "sloppy";
+import { SqlServer } from "sloppy/providers/sqlserver";
+
+type UserCreate = {
+    name: NonEmptyString;
+    email: Email;
+};
+
+type UserDto = {
+    id: number;
+    name: string;
+    email: string;
+};
+
+const app = Sloppy.create();
+
+app.get("/users", async (db: SqlServer<"main">, ctx: RequestContext) => {
+    const users = await db.query<UserDto>(
+        "select id, name, email from users order by id",
+        [],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    return Results.ok(users);
+}).withName("Users.List");
+
+app.get("/users/{id:int}", async (
+    id: Route<PositiveInt>,
+    db: SqlServer<"main">,
+    ctx: RequestContext,
+) => {
+    const user = await db.queryOne<UserDto>(
+        "select id, name, email from users where id = ?",
+        [id],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    return user === null ? Results.notFound() : Results.ok(user);
+}).withName("Users.Get");
+
+app.post("/users", async (
+    input: Body<UserCreate>,
+    db: SqlServer<"main">,
+    ctx: RequestContext,
+) => {
+    const user = await db.queryOne<UserDto>(
+        "insert into users (name, email) output inserted.id, inserted.name, inserted.email values (?, ?)",
+        [input.name, input.email],
+        { signal: ctx.signal, deadline: ctx.deadline },
+    );
+    if (user === null) {
+        throw new Error("SQL Server user insert did not return a row.");
+    }
+    return Results.created(`/users/${user.id}`, user);
+}).withName("Users.Create");
+
+export default app;

package/examples/framework-validation-errors/README.md

@@ -0,0 +1,12 @@
+# Framework Validation Errors Example
+
+A compile-time validation example.
+
+The handler keeps its request-body TypeScript shape visible to `sloppyc`, so the
+generated Plan schema metadata can drive native request validation before the
+handler is invoked.
+
+## Scope
+
+Negative-path coverage lives in validation conformance tests. Unsupported body
+formats are not covered here.

package/examples/framework-validation-errors/app.ts

@@ -0,0 +1,16 @@
+import { Sloppy, Results, Body } from "sloppy";
+
+type UserCreate = {
+    name: string;
+    email: string;
+};
+
+const app = Sloppy.create();
+
+app.post("/users", (
+    input: Body<UserCreate>,
+) => Results.created("/users/1", {
+    user: input,
+})).withName("Users.Create");
+
+export default app;

package/examples/fs-basic/README.md

@@ -0,0 +1,24 @@
+# Filesystem Basic Example
+
+This filesystem source example documents the intended
+`sloppy/fs` app-facing shape; full source-input execution remains gated by the V8 runtime
+path and current compiler support.
+
+This example uses project-relative paths for local development:
+
+```js
+import { Directory, File } from "sloppy/fs";
+import { Deadline } from "sloppy/time";
+
+await Directory.create("./tmp", { recursive: true });
+await File.writeJson("./tmp/users.json", [{ id: 1, name: "Ada" }], {
+    atomic: true,
+    indent: 2,
+});
+const deadline = Deadline.after(1000);
+const users = await File.readJson("./tmp/users.json", { deadline });
+```
+
+The read uses a Time deadline option. Deadline handling is cooperative; it does not
+preempt in-flight native filesystem calls. This example also focuses on Sloppy APIs rather
+than Node-style `fs` compatibility or sync APIs.

package/examples/fs-basic/app.js

@@ -0,0 +1,12 @@
+import { Directory, File } from "sloppy/fs";
+import { Deadline } from "sloppy/time";
+
+await Directory.create("./tmp", { recursive: true });
+await File.writeJson("./tmp/users.json", [{ id: 1, name: "Ada" }], {
+    atomic: true,
+    indent: 2,
+});
+
+const deadline = Deadline.after(1000);
+const users = await File.readJson("./tmp/users.json", { deadline });
+await File.writeText("./tmp/summary.txt", `users=${users.length}`);

package/examples/fs-roots-policy/README.md

@@ -0,0 +1,14 @@
+# Filesystem Roots And Policy Example
+
+This is a filesystem policy example.
+Named roots are the recommended Sloppy filesystem policy shape:
+
+```js
+import { Directory, File } from "sloppy/fs";
+
+await Directory.create("data:/exports", { recursive: true });
+await File.writeText("data:/exports/report.txt", "ready", { atomic: true });
+```
+
+Development mode may warn on absolute paths. Strict mode requires explicit policy for
+absolute and risky operations such as delete, watch, and lock.

package/examples/fs-roots-policy/app.js

@@ -0,0 +1,4 @@
+import { Directory, File } from "sloppy/fs";
+
+await Directory.create("data:/exports", { recursive: true });
+await File.writeText("data:/exports/report.txt", "ready", { atomic: true });

package/examples/fs-streams/README.md

@@ -0,0 +1,18 @@
+# Filesystem Streams Example
+
+This filesystem example shows Sloppy-owned `FileHandle` async iteration helpers.
+Node-style stream APIs are separate from this example.
+
+```js
+import { Directory, File } from "sloppy/fs";
+
+await Directory.create("./tmp", { recursive: true });
+const file = await File.open("data:/large.log", { access: "read" });
+try {
+    for await (const line of file.readLines()) {
+        await File.appendText("./tmp/filtered.log", `${line}\n`);
+    }
+} finally {
+    await file.close();
+}
+```

package/examples/fs-streams/app.js

@@ -0,0 +1,11 @@
+import { Directory, File } from "sloppy/fs";
+
+await Directory.create("./tmp", { recursive: true });
+const file = await File.open("data:/large.log", { access: "read" });
+try {
+    for await (const line of file.readLines()) {
+        await File.appendText("./tmp/filtered.log", `${line}\n`);
+    }
+} finally {
+    await file.close();
+}

package/examples/fs-watch/README.md

@@ -0,0 +1,19 @@
+# Filesystem Watch Example
+
+This is a filesystem watch example.
+The current watch API is resource-backed, bounded, and non-recursive. It reports
+create/modify/delete/overflow events while keeping Node `fs.watch` semantics separate:
+
+```js
+import { Directory, File } from "sloppy/fs";
+
+const watcher = await Directory.watch("./tmp", { queueCapacity: 16 });
+try {
+    for await (const event of watcher) {
+        await File.appendText("./tmp/watch-events.log", `${event.kind}:${event.path}\n`);
+        break;
+    }
+} finally {
+    await watcher.close();
+}
+```

package/examples/fs-watch/app.js

@@ -0,0 +1,11 @@
+import { Directory, File } from "sloppy/fs";
+
+const watcher = await Directory.watch("./tmp", { queueCapacity: 16 });
+try {
+    for await (const event of watcher) {
+        await File.appendText("./tmp/watch-events.log", `${event.kind}:${event.path}\n`);
+        break;
+    }
+} finally {
+    await watcher.close();
+}

package/examples/hello/README.md

@@ -0,0 +1,63 @@
+# Hello Example
+
+Bootstrap app-host example.
+This example shows the minimal app-host builder flow: config, logging, services, route
+mapping, and a text result descriptor. Runtime notes follow after the code.
+
+```js
+import { Sloppy, Results } from "sloppy";
+
+const builder = Sloppy.createBuilder();
+
+builder.config.addObject({
+    "app.name": "hello",
+});
+
+builder.logging.addMemorySink();
+builder.services.addSingleton("message", () => "Hello from Sloppy");
+
+const app = builder.build();
+
+app.log.info("hello example configured", { example: "hello" });
+
+app.mapGet("/", ({ services }) => Results.text(services.get("message")))
+    .withName("Hello.Index");
+
+export default app;
+```
+
+What to inspect:
+
+- `Sloppy.createBuilder()` creates a bootstrap builder with config, logging, and services.
+- `builder.config.addObject(...)` stores object-backed config values.
+- `builder.logging.addMemorySink()` installs a deterministic in-memory log sink.
+- `builder.services.addSingleton(...)` registers a string-token singleton service.
+- `builder.build()` creates an in-memory app facade and freezes builder mutation.
+- `app.log.info(...)` writes a structured application event into the configured sink.
+- `app.mapGet("/", handler)` records a conceptual GET route.
+- `.withName("Hello.Index")` stores the route name for the bootstrap shape.
+- Route handlers can receive a minimal context with `services`, `config`, and `log`.
+- `Results.text("Hello from Sloppy")` creates a frozen text result descriptor.
+- CTest statically verifies this example imports the public Sloppy facade and uses the
+  expected public API shape.
+
+Current product state:
+
+- This source-stdlib example is a checked-in API-shape fixture.
+- `sloppy run --artifacts` currently runs emitted artifacts such as
+  `examples/compiler-hello`.
+- `sloppyc` route extraction and `app.plan.json` emission for this broader
+  builder shape are planned separately.
+- `app.run` and `app.listen` belong to later app-host runtime work.
+- Direct `../../stdlib` imports are reserved for internal bootstrap tests; public examples
+  use the Sloppy facade import shape that `sloppyc` recognizes.
+
+Runtime Command:
+
+```powershell
+sloppy run examples/hello/app.js
+```
+
+That command documents the intended direct-source shape for this example. The
+current emitted-artifact runtime path is `examples/compiler-hello/`. This is a
+future user-facing shape for this example.

package/examples/hello/app.js

@@ -0,0 +1,19 @@
+import { Sloppy, Results } from "sloppy";
+
+const builder = Sloppy.createBuilder();
+
+builder.config.addObject({
+    "app.name": "hello",
+});
+
+builder.logging.addMemorySink();
+builder.services.addSingleton("message", () => "Hello from Sloppy");
+
+const app = builder.build();
+
+app.log.info("hello example configured", { example: "hello" });
+
+app.mapGet("/", ({ services }) => Results.text(services.get("message")))
+    .withName("Hello.Index");
+
+export default app;

package/examples/hello-minimal/README.md

@@ -0,0 +1,51 @@
+# Hello Minimal Example
+
+This example demonstrates the smallest useful Sloppy app: a health route and a
+parameterized JSON route using the current framework subset.
+
+## Requirements
+
+- A V8-enabled Sloppy build or package for handler execution.
+- PowerShell examples below assume Windows paths.
+
+## Run
+
+From this directory:
+
+```powershell
+..\..\build\windows-relwithdebinfo\sloppy.exe build
+..\..\build\windows-relwithdebinfo\sloppy.exe run --once GET /health
+..\..\build\windows-relwithdebinfo\sloppy.exe run --once GET /hello/Ada
+```
+
+Run from the repository root:
+
+```powershell
+.\build\windows-relwithdebinfo\sloppy.exe run examples/hello-minimal/src/main.ts --once GET /hello/Ada
+```
+
+## Expected Result
+
+- `GET /health` returns `ok`.
+- `GET /hello/Ada` returns `{"hello":"Ada"}`.
+
+## What To Inspect
+
+- `sloppy.json`: the source-input configuration.
+- `src/main.ts`: route binding and explicit `Results.text`/`Results.json`
+  helpers.
+- `.sloppy/app.plan.json`: generated route and handler metadata after
+  `sloppy build`.
+
+After building artifacts, inspect the generated app with:
+
+```powershell
+..\..\build\windows-relwithdebinfo\sloppy.exe routes --plan .sloppy\app.plan.json
+..\..\build\windows-relwithdebinfo\sloppy.exe doctor --plan .sloppy\app.plan.json
+..\..\build\windows-relwithdebinfo\sloppy.exe openapi --plan .sloppy\app.plan.json
+```
+
+## Current Limits
+
+This example requires V8 for handler execution and covers only the two routes
+shown above.

package/examples/hello-minimal/sloppy.json

@@ -0,0 +1,5 @@
+{
+  "entry": "src/main.ts",
+  "outDir": ".sloppy",
+  "environment": "Development"
+}

package/examples/hello-minimal/src/main.ts

@@ -0,0 +1,9 @@
+import { Sloppy, Results } from "sloppy";
+
+const app = Sloppy.create();
+
+app.get("/health", () => Results.text("ok")).withName("Health.Get");
+app.get("/hello/{name}", (ctx) => Results.json({ hello: ctx.route.name }))
+    .withName("Hello.Get");
+
+export default app;

package/examples/http-client-basic/README.md

@@ -0,0 +1,11 @@
+# HTTP Client Basic
+
+This source example shows the outbound `HttpClient` API shape from `sloppy/net`: reusable
+client creation, base URL joins, bounded response bodies, JSON helpers, redirect policy,
+per-origin pooling, and strict outbound-network metadata.
+
+## Limitations
+
+This example is limited to the outbound `HttpClient` API shape shown in source.
+Live external network behavior, TLS policy, proxy policy, UDP, and WebSocket
+behavior are separate examples or future runtime work.

package/examples/http-client-basic/app.js

@@ -0,0 +1,46 @@
+import { HttpClient } from "sloppy/net";
+
+const billing = HttpClient.create({
+    baseUrl: "https://billing.example.test",
+    timeoutMs: 5000,
+    maxResponseBytes: "4mb",
+    headers: {
+        "user-agent": "sloppy-http-client-example"
+    },
+    redirects: {
+        enabled: true,
+        max: 5,
+        crossOriginSensitiveHeaders: "strip"
+    },
+    pool: {
+        maxConnectionsPerOrigin: 8,
+        idleTimeoutMs: 30000
+    },
+    network: {
+        strict: true,
+        allow: ["https://billing.example.test"]
+    }
+});
+
+async function loadHealth() {
+    const response = await billing.get("/health", { timeoutMs: 2000 });
+    return await response.json();
+}
+
+async function createInvoice(customerId) {
+    const response = await billing.postJson("/invoices", { customerId });
+    if (response.status !== 201) {
+        throw new Error(`invoice create failed with status ${response.status}`);
+    }
+    return await response.json();
+}
+
+async function loadTextStatus() {
+    return await HttpClient.text("http://127.0.0.1:8080/status", {
+        timeoutMs: 1000,
+        redirects: { enabled: false },
+        maxResponseBytes: 4096
+    });
+}
+
+export { billing, createInvoice, loadHealth, loadTextStatus };

package/examples/http-client-generated/README.md

@@ -0,0 +1,22 @@
+# Generated HTTP Client
+
+This example shows the generated-client shape produced from a Sloppy OpenAPI
+artifact. The generator returns JavaScript source that uses first-party
+`Http.typedClient(...)` and `Config.required(...)`.
+
+```js
+import { File } from "sloppy/fs";
+import { Http } from "sloppy/http";
+
+const document = await File.readJson("openapi.json");
+const generated = Http.generateClientFromOpenApi(document, {
+    name: "Billing",
+    baseUrlConfigKey: "Billing:BaseUrl",
+});
+
+await File.writeText("billing.client.js", generated.source);
+```
+
+`tests/bootstrap/test_http_client_factory.mjs` covers deterministic generated
+output, importability, unsupported-schema warnings, and a generated client call
+against `TestHttp.mock()`.

package/examples/http-client-generated/openapi.json

@@ -0,0 +1,45 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Billing",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/invoices/{id}": {
+      "get": {
+        "operationId": "getInvoice",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Invoice",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Invoice" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Invoice": {
+        "type": "object",
+        "required": ["id", "status", "amount"],
+        "properties": {
+          "id": { "type": "string" },
+          "status": { "type": "string" },
+          "amount": { "type": "number" }
+        }
+      }
+    }
+  }
+}