skir-simple-data-objects-generator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxim Kerstens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# Skir Simple Data Objects Generator
+
+[![Tests](https://github.com/php-skir/skir-simple-data-objects-generator/actions/workflows/tests.yml/badge.svg)](https://github.com/php-skir/skir-simple-data-objects-generator/actions/workflows/tests.yml)
+[![Coverage](https://raw.githubusercontent.com/php-skir/skir-simple-data-objects-generator/badges/coverage.svg)](https://github.com/php-skir/skir-simple-data-objects-generator/actions/workflows/tests.yml)
+[![npm](https://img.shields.io/npm/v/skir-simple-data-objects-generator?label=npm&logo=npm)](https://www.npmjs.com/package/skir-simple-data-objects-generator)
+[![Node.js](https://img.shields.io/badge/Node.js-22%20%7C%2024-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/php-skir/skir-simple-data-objects-generator)](LICENSE)
+
+Generates [`std-out/simple-data-objects`](https://github.com/std-out/simple-data-objects) DTOs, typed RPC clients, and server procedure contracts from Skir schemas.
+
+Generated PHP uses `php-skir/runtime` for Skir wire formats and `std-out/simple-data-objects` for immutable DTO hydration, mapped property names, typed collections, serialization, and validation.
+
+## Quick start
+
+Prerequisites: PHP 8.4 or newer, Composer 2, and a supported Node.js release.
+
+Install Skir and this generator as development dependencies, then install the PHP runtime and DTO library:
+
+```bash
+npm install --save-dev skir skir-simple-data-objects-generator
+composer require php-skir/runtime std-out/simple-data-objects
+```
+
+Create `skir-src/users.skir`:
+
+```skir
+struct User {
+  user_id: int32;
+  email: string;
+  nickname: string?;
+}
+```
+
+Add the generator to the root `skir.yml`:
+
+```yaml
+generators:
+  - mod: skir-simple-data-objects-generator
+    outDir: generated/php/skirout
+    config:
+      namespace: Skir
+      validation:
+        users.skir:
+          User:
+            email:
+              - email
+```
+
+Generate the PHP files and configure Composer autoloading:
+
+```bash
+npx skir gen
+npx skir-simple-data-objects-generator configure-composer
+composer dump-autoload
+```
+
+The generated `Skir\UserData` class is now ready to use:
+
+```php
+use Skir\UserData;
+
+$user = UserData::makeFromSkirPayload([
+    'user_id' => 400,
+    'email' => 'maxim@example.com',
+]);
+
+$json = $user->toSkirJson();
+$decoded = UserData::fromSkir($json);
+
+$decoded->userId; // 400
+$decoded->nickname; // null
+```
+
+The root namespace defaults to `Skir`, so `config.namespace` is optional when that default is suitable.
+
+## Generated output is owned by Skir
+
+Skir owns the configured `outDir` and may replace or delete anything inside it. Use a dedicated path ending in `/skirout`, do not put handwritten PHP there, and never edit a generated file. Change the `.skir` source or generator configuration and regenerate instead.
+
+Source directories below `skir-src` become PHP subnamespaces and output directories. The `.skir` filename itself does not add a namespace segment:
+
+```text
+skir-src/admin/users.skir -> generated/php/skirout/Admin/UserData.php
+                          -> Skir\Admin\UserData
+```
+
+Generated struct and enum class names end in `Data`. A Skir field such as `user_id` becomes the PHP property `$userId`, with `#[MapPropertyName('user_id')]` preserving the original name for hydration and `toArray()` output.
+
+## Composer configuration
+
+Run Skir generation before `configure-composer`: the command verifies that every configured output directory exists before changing `composer.json`.
+
+```text
+skir-simple-data-objects-generator configure-composer [--root <dir>] [--mod <module>]
+```
+
+In a normal npm project, invoke it through `npx`:
+
+```bash
+npx skir-simple-data-objects-generator configure-composer
+```
+
+The command reads `skir.yml` and `composer.json`, finds the exact `mod: skir-simple-data-objects-generator` entry, and adds the configured namespace and `outDir` as a Composer PSR-4 mapping. It changes only `composer.json`; run `composer dump-autoload` afterward.
+
+Use `--root <dir>` for another project root. Use `--mod <module>` when the configured module is an exact alternative identifier, such as a local file URL:
+
+```bash
+npx skir-simple-data-objects-generator configure-composer \
+  --root ../api \
+  --mod file:///path/to/skir-simple-data-objects-generator/dist/index.js
+```
+
+An equivalent existing mapping is left byte-for-byte unchanged. A conflicting mapping, invalid configuration, missing output directory, or path outside the project root fails without modifying `composer.json`.
+
+## Generated data objects
+
+### Struct APIs
+
+Every Skir struct generates a final class extending `StdOut\SimpleDataObjects\BaseData`. In addition to its readonly constructor properties, it exposes:
+
+| Method | Purpose |
+| --- | --- |
+| `skirType()` | Return the runtime `Type` descriptor. |
+| `makeFromSkirPayload(array $data)` | Validate raw named Skir data, recursively hydrate nested values, and return the DTO. |
+| `fromSkir(string $json)` | Decode dense Skir JSON and delegate to `makeFromSkirPayload()`. |
+| `toSkirArray()` | Convert DTO values to the named array representation expected by the runtime. |
+| `toSkir()` | Encode the DTO as the dense PHP array representation. |
+| `toSkirJson()` | Encode the DTO as dense Skir JSON. |
+
+Generated classes inherit the current `BaseData` APIs, including `from()`, `fromValidated()`, `validate()`, `toArray()`, `toJson()`, `with()`, `equals()`, `diff()`, `only()`, `except()`, `collection()`, and `lazyCollection()`.
+
+Use PHP property names with `with()`, but original Skir names in raw payloads and serialized arrays:
+
+```php
+$updated = $user->with(userId: 401);
+
+$updated->userId; // 401
+$updated->toArray()['user_id']; // 401
+$updated->equals($user); // false
+```
+
+`BaseData::from()` hydrates without validation. Use `makeFromSkirPayload()` for raw Skir data: it applies the generated validation contract and performs the Skir-specific recursive conversions before calling `BaseData::from()`.
+
+`BaseData::collection()`, `BaseData::lazyCollection()`, and `TypedDataCollection::of()` are also trusted hydration paths. Like `from()`, they do not execute generated `#[Rules]` validation. Construct collections from DTOs or other trusted values:
+
+```php
+use Skir\AddressData;
+
+$addresses = AddressData::collection([
+    AddressData::makeFromSkirPayload([
+        'city' => 'Antwerp',
+        'postal_codes' => ['2000'],
+    ]),
+]);
+
+foreach ($addresses as $address) {
+    echo $address->city;
+}
+```
+
+For untrusted raw item arrays, call `AddressData::makeFromSkirPayload()` for each item before constructing a collection. When the collection belongs to a generated parent DTO or RPC request, prefer passing the complete raw parent payload through the parent's `makeFromSkirPayload()` or generated RPC hydration path; those paths validate each nested struct before collection construction.
+
+### Struct collections
+
+Only a direct array of structs becomes a `TypedDataCollection`:
+
+| Skir shape | Generated PHP type |
+| --- | --- |
+| `[Address]` | `TypedDataCollection` with `#[DataCollection(AddressData::class)]` |
+| `[Address]?` | `?TypedDataCollection` with the same collection attribute |
+| `[[Address]]` | `array` |
+| `[Address?]` | `array` |
+| `[string]` or `[SomeEnum]` | `array` |
+
+Nested arrays and arrays whose item is optional remain normal PHP arrays, although supported nested structs and enum wrappers are still converted recursively.
+
+### Wrapper enums
+
+Skir enums generate readonly wrapper classes with a `Data` suffix. Constant variants have parameterless named constructors; payload variants have typed named constructors. Generated enum classes expose `name()`, `payload()`, `skirType()`, `toSkirValue()`, `fromSkirValue()`, `toDenseValue()`, `fromDenseValue()`, `toDenseJson()`, and `fromDenseJson()`.
+
+Structs, typed struct collections, nested arrays, optionals, and nested enum wrappers are converted to wire values when stored in a wrapper and converted back to target DTO values when `payload()` is read.
+
+## Validation
+
+The generator emits `#[Rules]` attributes understood by Simple Data Objects and Laravel's validator. Rules are deterministic: generated structural rules come first, followed by configured string rules in their exact configured order.
+
+### Structural rules
+
+Every non-optional field starts with `required`. Every optional field starts with `nullable`, so the key may be omitted or its value may be `null`. A safely representable shape rule follows when available:
+
+| Skir type | Generated shape rule |
+| --- | --- |
+| `bool` | `boolean` |
+| `int32`, `timestamp` | `integer` |
+| `float32`, `float64` | `numeric` |
+| `string`, `bytes` | `string` |
+| any array | `array` |
+| struct reference | `array` |
+| enum reference, `mixed` | none |
+| `int64`, `hash64` | none |
+
+`int64` and `hash64` deliberately receive no narrowing rule because their PHP representation is `int|string`.
+
+Array validation is structural only at the field level. The generator emits `array`, but not wildcard item rules such as `field.*`. Array-shaped nested structs are recursively hydrated through their own `makeFromSkirPayload()` method and therefore run their own field rules. Put additional element constraints in custom named rules or at a handwritten application boundary.
+
+### Validation and hydration order
+
+`makeFromSkirPayload()` processes input in this order:
+
+1. Validate the raw parent array with `self::validate($data)`.
+2. Convert mapped names and recursively hydrate nested structs, collections, arrays, and enum wrappers. Each nested struct validates its own raw array before hydration.
+3. Pass the already validated and prepared values to `self::from($payload)`.
+
+Generated RPC providers use the same raw-to-target conversion for incoming requests, and generated clients use it for responses. Direct struct requests and every recursively hydrated nested struct are validated before application code receives them.
+
+The final `BaseData::from()` call is intentionally a hydration-only operation and does not validate by itself. Calling `SomeData::from($untrustedInput)` directly bypasses the generated raw-first validation sequence.
+
+### Validation overlays
+
+Configure application-specific rules under `config.validation` in `skir.yml`:
+
+```yaml
+generators:
+  - mod: skir-simple-data-objects-generator
+    outDir: generated/php/skirout
+    config:
+      namespace: Skir
+      validation:
+        admin/users.skir:
+          "Envelope.Metadata":
+            display_name:
+              - min:2
+              - max:80
+            email_address:
+              - email:rfc
+              - company_email
+```
+
+Selectors use the original Skir identities, in this order:
+
+1. Module path relative to `skir-src`, such as `admin/users.skir`.
+2. Qualified record name, such as `Envelope.Metadata`.
+3. Original Skir field name, such as `display_name`, not the generated `$displayName` property.
+
+Unknown modules, records, or fields fail generation instead of silently dropping a rule. Enum variants, removed fields, and other non-struct payload fields cannot receive validation overlays.
+
+Only non-empty string rules can be encoded in `skir.yml`. The generator appends them after structural rules without reordering them. Register every custom named rule before generated DTO validation runs.
+
+### Register custom rules in Laravel
+
+Laravel's validator is available to `BaseData` through the application container. Register custom named rules during application boot:
+
+```php
+namespace App\Providers;
+
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Support\ServiceProvider;
+
+final class AppServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        Validator::extend(
+            'company_email',
+            static fn (string $attribute, mixed $value): bool =>
+                is_string($value) && str_ends_with($value, '@company.test'),
+        );
+    }
+}
+```
+
+Register the rule before any generated `makeFromSkirPayload()`, `fromSkir()`, or RPC hydration call that may use it.
+
+### Register custom rules without Laravel
+
+Standalone applications can create and install an Illuminate validator factory:
+
+```php
+use Illuminate\Translation\ArrayLoader;
+use Illuminate\Translation\Translator;
+use Illuminate\Validation\Factory as ValidatorFactory;
+use StdOut\SimpleDataObjects\BaseData;
+
+$validator = new ValidatorFactory(
+    new Translator(new ArrayLoader(), 'en'),
+);
+$validator->extend(
+    'company_email',
+    static fn (string $attribute, mixed $value): bool =>
+        is_string($value) && str_ends_with($value, '@company.test'),
+);
+
+BaseData::setValidatorFactory($validator);
+```
+
+Install the configured factory before the first generated validation call.
+
+### Handwritten validation boundaries
+
+Laravel rule objects and closures cannot be represented in `skir.yml`; only strings are portable generator configuration. Keep request-specific authorization, database-aware rules, uploaded-file rules, closure rules, normalization, and other application behavior in a handwritten Laravel Form Request or equivalent application-owned validation boundary.
+
+That boundary must live outside `skirout`, because regeneration overwrites generated files. It complements the generated wire-shape and named-rule validation instead of modifying generated DTOs.
+
+## RPC clients, procedures, and manifests
+
+When a schema contains methods, the generator emits six module-scoped PHP RPC files plus `skir-server-manifest.json`:
+
+- `SkirMethods.php` with runtime `MethodDescriptor` instances.
+- A module method enum such as `AdminSkirMethod.php`.
+- `SkirRpcClient.php` with typed request and response conversion.
+- `SkirProcedures.php` and `AbstractSkirProcedures.php` for implementation contracts.
+- `SkirProcedureProvider.php` for server registration.
+- `skir-server-manifest.json` with exact module and method identities and `Data`-suffixed struct and enum classes.
+
+Install the client package when using the generated RPC client:
+
+```bash
+composer require php-skir/client
+```
+
+Install the server package when using generated procedure contracts or providers:
+
+```bash
+composer require php-skir/server
+```
+
+RPC methods retain target types at the application boundary. Direct struct collections are accepted and returned as `TypedDataCollection`; nested collection shapes remain arrays. The generated client converts requests to raw Skir values and hydrates responses. The generated providers validate and hydrate incoming raw values before calling application code, then convert returned DTOs back to Skir values.
+
+This generator emits contracts and conversions only. HTTP transport and server routing remain the responsibility of `php-skir/client`, `php-skir/server`, and the application.
+
+## Development and contributing
+
+Install dependencies and run the complete package verification sequence:
+
+```bash
+npm ci
+npm run typecheck
+npm run build
+npm run pack:dry-run
+SKIR_RUNTIME_PATH=../runtime npm test
+git diff --check
+```
+
+The integration tests require PHP 8.4, Composer, and a local checkout of `php-skir/runtime`. Pull requests should keep generated output behavior covered by source assertions and executable PHP integration tests.
+
+### Develop against a local generator core
+
+Build the core first. Before the initial compatible core release and adapter lockfile commit, one no-save install can install this package's development dependencies and satisfy `@php-skir/generator-core` from the local checkout without creating a lockfile:
+
+```bash
+cd ../generator-core
+npm ci
+npm run build
+
+cd ../skir-simple-data-objects-generator
+npm install --no-save --package-lock=false ../generator-core
+```
+
+Once the compatible core package has been published and this repository has committed its normal `package-lock.json`, use `npm ci` instead of the local-path bootstrap.
+
+## Releasing
+
+Release the shared packages in dependency order:
+
+1. Merge and publish `@php-skir/generator-core` with the required adapter APIs.
+2. Replace the local link with the published compatible core version and commit the resulting `package-lock.json` update.
+3. Run `npm ci`, typecheck, build, package validation, the full test suite, and `git diff --check` again.
+4. Create the Simple Data Objects generator release only after those checks pass.
+
+The release workflow uses Node 24 and npm trusted publishing with provenance. Configure this GitHub repository as an npm trusted publisher before publishing; no release or publish action is performed by the test workflow.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { runConfigureComposerCli } from "@php-skir/generator-core";
+import { GeneratorConfig, GENERATOR_MODULE } from "./config.js";
+async function main() {
+    try {
+        await runConfigureComposerCli({
+            argv: process.argv.slice(2),
+            bin: "skir-simple-data-objects-generator",
+            module: GENERATOR_MODULE,
+            parseConfig: (value) => GeneratorConfig.parse(value),
+            namespace: (config) => config.namespace,
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+void main();

package/dist/composer-autoload.d.ts

@@ -0,0 +1,2 @@
+export { ComposerAutoloadConflictError, ensureComposerPsr4Mapping, MalformedComposerPsr4PrefixError, } from "@php-skir/generator-core";
+export type { ComposerAutoloadPaths, ComposerPsr4MappingResult, } from "@php-skir/generator-core";

package/dist/composer-autoload.js

@@ -0,0 +1 @@
+export { ComposerAutoloadConflictError, ensureComposerPsr4Mapping, MalformedComposerPsr4PrefixError, } from "@php-skir/generator-core";

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import { DEFAULT_NAMESPACE, PhpNamespace } from "@php-skir/generator-core";
+import { z } from "zod";
+export declare const GENERATOR_MODULE = "skir-simple-data-objects-generator";
+export { DEFAULT_NAMESPACE, PhpNamespace };
+export declare const GeneratorConfig: z.ZodObject<{
+    namespace: z.ZodDefault<z.ZodString>;
+    validation: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>>>;
+}, z.core.$strict>;
+export type GeneratorConfig = z.infer<typeof GeneratorConfig>;
+export type GeneratorConfigInput = z.input<typeof GeneratorConfig>;

package/dist/config.js

@@ -0,0 +1,8 @@
+import { DEFAULT_NAMESPACE, PhpNamespace, ValidationConfig, } from "@php-skir/generator-core";
+import { z } from "zod";
+export const GENERATOR_MODULE = "skir-simple-data-objects-generator";
+export { DEFAULT_NAMESPACE, PhpNamespace };
+export const GeneratorConfig = z.strictObject({
+    namespace: PhpNamespace.default(DEFAULT_NAMESPACE),
+    validation: ValidationConfig.optional(),
+});

package/dist/configure-composer.d.ts

@@ -0,0 +1,6 @@
+import { type ComposerPsr4MappingResult } from "@php-skir/generator-core";
+export interface ConfigureComposerOptions {
+    readonly mod?: string;
+    readonly root?: string;
+}
+export declare function configureComposer(options?: ConfigureComposerOptions): Promise<ComposerPsr4MappingResult>;

package/dist/configure-composer.js

@@ -0,0 +1,10 @@
+import { configureComposer as configureCoreComposer, } from "@php-skir/generator-core";
+import { GeneratorConfig, GENERATOR_MODULE } from "./config.js";
+export function configureComposer(options = {}) {
+    return configureCoreComposer({
+        module: options.mod ?? GENERATOR_MODULE,
+        ...(options.root === undefined ? {} : { root: options.root }),
+        parseConfig: (value) => GeneratorConfig.parse(value),
+        namespace: (config) => config.namespace,
+    });
+}

package/dist/generator.d.ts

@@ -0,0 +1,9 @@
+import { PHP_FILE_HEADER, type CoreGeneratorInput, type GeneratedFile } from "@php-skir/generator-core";
+import { type GeneratorConfigInput } from "./config.js";
+export { PHP_FILE_HEADER };
+export type PhpGeneratorConfig = GeneratorConfigInput;
+export interface PhpGeneratorInput extends CoreGeneratorInput {
+    readonly config?: PhpGeneratorConfig;
+}
+export declare function generateSimpleDataObjectsFiles(input: PhpGeneratorInput): GeneratedFile[];
+export type { GeneratedFile, SkirField, SkirMethod, SkirModule, SkirRecord, SkirRecordLocation, SkirRecordNamePart, SkirToken, SkirType, } from "@php-skir/generator-core";

package/dist/generator.js

@@ -0,0 +1,12 @@
+import { generatePhp, PHP_FILE_HEADER, } from "@php-skir/generator-core";
+import { GeneratorConfig, } from "./config.js";
+import { SimpleDataObjectsTarget } from "./target.js";
+export { PHP_FILE_HEADER };
+export function generateSimpleDataObjectsFiles(input) {
+    const { namespace, validation = {} } = GeneratorConfig.parse(input.config ?? {});
+    return generatePhp({
+        ...input,
+        namespace,
+        adapter: new SimpleDataObjectsTarget(validation),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { type CodeGenerator } from "skir-internal";
+import { GeneratorConfig } from "./config.js";
+import { generateSimpleDataObjectsFiles } from "./generator.js";
+declare class SimpleDataObjectsGenerator implements CodeGenerator<GeneratorConfig> {
+    readonly id = "skir-simple-data-objects-generator";
+    readonly configType: CodeGenerator<GeneratorConfig>["configType"];
+    generateCode(input: CodeGenerator.Input<GeneratorConfig>): CodeGenerator.Output;
+}
+export declare const GENERATOR: SimpleDataObjectsGenerator;
+export { generateSimpleDataObjectsFiles };
+export { SimpleDataObjectsTarget } from "./target.js";
+export default GENERATOR;

package/dist/index.js

@@ -0,0 +1,15 @@
+import { GeneratorConfig, GENERATOR_MODULE } from "./config.js";
+import { generateSimpleDataObjectsFiles } from "./generator.js";
+class SimpleDataObjectsGenerator {
+    id = GENERATOR_MODULE;
+    configType = GeneratorConfig;
+    generateCode(input) {
+        return {
+            files: generateSimpleDataObjectsFiles(input),
+        };
+    }
+}
+export const GENERATOR = new SimpleDataObjectsGenerator();
+export { generateSimpleDataObjectsFiles };
+export { SimpleDataObjectsTarget } from "./target.js";
+export default GENERATOR;

package/dist/structural-rules.d.ts

@@ -0,0 +1,2 @@
+import { type NormalizedType } from "@php-skir/generator-core";
+export declare function structuralRules(type: NormalizedType, optional?: boolean): readonly string[];

package/dist/structural-rules.js

@@ -0,0 +1,26 @@
+export function structuralRules(type, optional = type.kind === "optional") {
+    const presence = optional ? "nullable" : "required";
+    const inner = type.kind === "optional" ? type.inner : type;
+    const shape = (() => {
+        switch (inner.kind) {
+            case "bool":
+                return "boolean";
+            case "int32":
+            case "timestamp":
+                return "integer";
+            case "float32":
+            case "float64":
+                return "numeric";
+            case "string":
+            case "bytes":
+                return "string";
+            case "array":
+                return "array";
+            case "record":
+                return inner.recordType === "struct" ? "array" : null;
+            default:
+                return null;
+        }
+    })();
+    return shape === null ? [presence] : [presence, shape];
+}

package/dist/target.d.ts

@@ -0,0 +1,29 @@
+import { type GeneratedFile, type NormalizedMethod, type NormalizedRecord, type NormalizedSchema, type NormalizedType, type PhpTargetAdapter, type RenderContext, type StructRenderRequest, type ValidationConfig } from "@php-skir/generator-core";
+export declare class SimpleDataObjectsTarget implements PhpTargetAdapter {
+    private readonly validation;
+    readonly id = "skir-simple-data-objects-generator";
+    private resolvedValidationRules;
+    constructor(validation?: ValidationConfig);
+    prepare(schema: NormalizedSchema): void;
+    recordClassName(record: NormalizedRecord): string;
+    structImports(record: NormalizedRecord): readonly string[];
+    enumImports(record: NormalizedRecord): readonly string[];
+    rpcImports(methods: readonly NormalizedMethod[]): readonly string[];
+    renderStruct({ record, context }: StructRenderRequest): GeneratedFile;
+    phpType(type: NormalizedType, context: RenderContext): string;
+    toSkirExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    fromSkirExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    clientResponseExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    enumPayloadToSkirExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    enumPayloadFromSkirExpression(type: NormalizedType, expression: string, context: RenderContext): string;
+    manifestObjectClass(type: NormalizedType, context: RenderContext): string | null;
+    manifestPhpType(type: NormalizedType): string | null;
+    private renderConstructor;
+    private renderSkirType;
+    private renderMakeFromSkirPayload;
+    private renderFromSkir;
+    private renderToSkirArray;
+    private renderToSkir;
+    private renderToSkirJson;
+    private toSkirValueExpression;
+}

package/dist/target.js

@@ -0,0 +1,498 @@
+import { importClass, importClassAs, indent, renderPhpFile, renderUseStatements, resolveValidationRules, toClassName, toPhpNamespaceSegment, toPropertyName, } from "@php-skir/generator-core";
+import { GENERATOR_MODULE } from "./config.js";
+import { structuralRules } from "./structural-rules.js";
+const DENSE_JSON = "Skir\\Runtime\\DenseJson";
+const FIELD = "Skir\\Runtime\\Field";
+const TYPE = "Skir\\Runtime\\Type";
+const DATA_COLLECTION = "StdOut\\SimpleDataObjects\\Attributes\\DataCollection";
+const MAP_PROPERTY_NAME = "StdOut\\SimpleDataObjects\\Attributes\\MapPropertyName";
+const RULES = "StdOut\\SimpleDataObjects\\Attributes\\Rules";
+const BASE_DATA = "StdOut\\SimpleDataObjects\\BaseData";
+const TYPED_DATA_COLLECTION = "StdOut\\SimpleDataObjects\\TypedDataCollection";
+const BASE_STRUCT_IMPORTS = [DENSE_JSON, FIELD, TYPE, BASE_DATA];
+export class SimpleDataObjectsTarget {
+    validation;
+    id = GENERATOR_MODULE;
+    resolvedValidationRules = new Map();
+    constructor(validation = {}) {
+        this.validation = validation;
+    }
+    prepare(schema) {
+        this.resolvedValidationRules = new Map();
+        this.resolvedValidationRules = resolveValidationRules(schema, this.validation);
+    }
+    recordClassName(record) {
+        if (record.phpClassName !== undefined) {
+            return record.phpClassName;
+        }
+        const className = toClassName(record.qualifiedName);
+        return className.endsWith("Data") ? className : `${className}Data`;
+    }
+    structImports(record) {
+        const fields = record.fields.filter(isStructField);
+        const imports = [...BASE_STRUCT_IMPORTS];
+        if (fields.some((field) => toPropertyName(field.name) !== field.name)) {
+            imports.push(MAP_PROPERTY_NAME);
+        }
+        if (fields.length > 0) {
+            imports.push(RULES);
+        }
+        if (fields.some((field) => dataCollectionType(field.type) !== null)) {
+            imports.push(DATA_COLLECTION, TYPED_DATA_COLLECTION);
+        }
+        return imports;
+    }
+    enumImports(record) {
+        if (record.recordType !== "enum") {
+            return [];
+        }
+        const needsTypedDataCollection = record.fields.some((field) => (field.kind === "field"
+            && field.hasPayload
+            && requiresTypedDataCollection(field.type)));
+        return needsTypedDataCollection ? [TYPED_DATA_COLLECTION] : [];
+    }
+    rpcImports(methods) {
+        const needsTypedDataCollection = methods.some((method) => (requiresTypedDataCollection(method.requestType)
+            || requiresTypedDataCollection(method.responseType)));
+        return needsTypedDataCollection ? [TYPED_DATA_COLLECTION] : [];
+    }
+    renderStruct({ record, context }) {
+        if (record.recordType !== "struct") {
+            throw new Error(`Cannot render non-struct record ${record.identity} as a struct.`);
+        }
+        const className = classNameForRecord(record, context);
+        const imports = this.structImports(record);
+        const denseJson = importClass(context.imports, DENSE_JSON);
+        const fieldClass = importClass(context.imports, FIELD);
+        const typeClass = importClass(context.imports, TYPE);
+        const baseData = importClass(context.imports, BASE_DATA);
+        const fields = record.fields.filter(isStructField);
+        const constructor = this.renderConstructor(record, fields, context);
+        const members = [
+            constructor,
+            this.renderSkirType(record, context, fieldClass, typeClass),
+            this.renderMakeFromSkirPayload(fields, context),
+            this.renderFromSkir(className, denseJson),
+            this.renderToSkirArray(fields, context),
+            this.renderToSkir(denseJson),
+            this.renderToSkirJson(denseJson),
+        ].filter((member) => member !== null);
+        const body = [
+            `final class ${className} extends ${baseData}`,
+            "{",
+            ...members.flatMap((member, index) => index === 0
+                ? [indent(member)]
+                : ["", indent(member)]),
+            "}",
+        ].join("\n");
+        return {
+            path: outputPath(context, `${className}.php`),
+            code: renderPhpFile({
+                namespace: context.namespace,
+                imports: renderUseStatements(context.imports, imports),
+                body,
+            }),
+        };
+    }
+    phpType(type, context) {
+        if (type.kind === "bool") {
+            return "bool";
+        }
+        if (type.kind === "int32" || type.kind === "timestamp") {
+            return "int";
+        }
+        if (type.kind === "int64" || type.kind === "hash64") {
+            return "int|string";
+        }
+        if (type.kind === "float32" || type.kind === "float64") {
+            return "float";
+        }
+        if (type.kind === "string" || type.kind === "bytes") {
+            return "string";
+        }
+        if (type.kind === "array") {
+            return isDirectStructCollection(type)
+                ? importClass(context.imports, TYPED_DATA_COLLECTION)
+                : "array";
+        }
+        if (type.kind === "optional") {
+            return nullablePhpType(this.phpType(type.inner, context));
+        }
+        if (type.kind === "record") {
+            return recordTypeClassName(type, context);
+        }
+        return "mixed";
+    }
+    toSkirExpression(type, expression, context) {
+        return this.toSkirValueExpression(type, expression, context, true);
+    }
+    fromSkirExpression(type, expression, context) {
+        return valueFromTargetExpression(type, expression, context);
+    }
+    clientResponseExpression(type, expression, context) {
+        return valueFromTargetExpression(type, expression, context);
+    }
+    enumPayloadToSkirExpression(type, expression, context) {
+        return this.toSkirValueExpression(type, expression, context, true);
+    }
+    enumPayloadFromSkirExpression(type, expression, context) {
+        return valueFromTargetExpression(type, expression, context);
+    }
+    manifestObjectClass(type, context) {
+        if (type.kind !== "record") {
+            return null;
+        }
+        const className = context.names.namesByIdentity.get(type.recordIdentity);
+        if (className === undefined) {
+            throw new Error(`No PHP class name was resolved for record ${type.recordIdentity}.`);
+        }
+        return canonicalRecordClassName(recordNamespace(type.recordIdentity, context.rootNamespace), className);
+    }
+    manifestPhpType(type) {
+        return isDirectStructCollection(type) ? TYPED_DATA_COLLECTION : null;
+    }
+    renderConstructor(record, fields, context) {
+        if (fields.length === 0) {
+            return null;
+        }
+        const validationRules = this.resolvedValidationRules.get(record.identity) ?? new Map();
+        return [
+            "public function __construct(",
+            ...fields.flatMap((field) => [
+                ...propertyAttributes(field, context, validationRules.get(field.name) ?? []).map((attribute) => `    ${attribute}`),
+                `    public readonly ${this.phpType(field.type, context)} $${toPropertyName(field.name)},`,
+            ]),
+            ") {}",
+        ].join("\n");
+    }
+    renderSkirType(record, context, fieldClass, typeClass) {
+        const entries = record.fields.map((field) => {
+            if (field.kind === "removed") {
+                return `        ${fieldClass}::removed(${field.number}),`;
+            }
+            if (!field.hasPayload) {
+                throw new Error(`Struct field ${field.name} in ${record.identity} has no payload type.`);
+            }
+            return `        ${fieldClass}::value(${phpSingleQuotedLiteral(field.name)}, ${field.number}, ${runtimeTypeExpression(field.type, context, this, typeClass)}),`;
+        });
+        if (entries.length === 0) {
+            return [
+                `public static function skirType(): ${typeClass}`,
+                "{",
+                `    return ${typeClass}::struct([]);`,
+                "}",
+            ].join("\n");
+        }
+        return [
+            `public static function skirType(): ${typeClass}`,
+            "{",
+            `    return ${typeClass}::struct([`,
+            entries.join("\n"),
+            "    ]);",
+            "}",
+        ].join("\n");
+    }
+    renderMakeFromSkirPayload(fields, context) {
+        const payload = fields.length === 0
+            ? ["    $payload = [];"]
+            : [
+                "    $payload = [",
+                ...fields.map((field) => renderPayloadEntry(field, context)),
+                "    ];",
+            ];
+        return [
+            "/** @param array<string, mixed> $data */",
+            "public static function makeFromSkirPayload(array $data): self",
+            "{",
+            "    self::validate($data);",
+            "",
+            ...payload,
+            "",
+            "    return self::from($payload);",
+            "}",
+        ].join("\n");
+    }
+    renderFromSkir(className, denseJson) {
+        return [
+            `public static function fromSkir(string $json): ${className}`,
+            "{",
+            `    $data = ${denseJson}::fromJson(self::skirType(), $json);`,
+            "",
+            "    return self::makeFromSkirPayload($data);",
+            "}",
+        ].join("\n");
+    }
+    renderToSkirArray(fields, context) {
+        if (fields.length === 0) {
+            return [
+                "/** @return array<string, mixed> */",
+                "public function toSkirArray(): array",
+                "{",
+                "    return [];",
+                "}",
+            ].join("\n");
+        }
+        return [
+            "/** @return array<string, mixed> */",
+            "public function toSkirArray(): array",
+            "{",
+            "    return [",
+            ...fields.map((field) => {
+                const expression = this.toSkirExpression(field.type, `$this->${toPropertyName(field.name)}`, context);
+                return renderArrayEntry(field.name, expression, 8);
+            }),
+            "    ];",
+            "}",
+        ].join("\n");
+    }
+    renderToSkir(denseJson) {
+        return [
+            "/** @return array<int, mixed> */",
+            "public function toSkir(): array",
+            "{",
+            `    return ${denseJson}::encode(self::skirType(), $this->toSkirArray());`,
+            "}",
+        ].join("\n");
+    }
+    renderToSkirJson(denseJson) {
+        return [
+            "public function toSkirJson(): string",
+            "{",
+            `    return ${denseJson}::toJson(self::skirType(), $this->toSkirArray());`,
+            "}",
+        ].join("\n");
+    }
+    toSkirValueExpression(type, expression, context, allowTypedCollection) {
+        if (type.kind === "record") {
+            return type.recordType === "enum"
+                ? `${expression}->toSkirValue()`
+                : `${expression}->toSkirArray()`;
+        }
+        if (type.kind === "optional") {
+            if (isRecursivelyMappedType(type.inner)) {
+                return `${expression} === null ? null : ${this.toSkirValueExpression(type.inner, expression, context, allowTypedCollection)}`;
+            }
+            return expression;
+        }
+        if (type.kind === "array" && isRecursivelyMappedType(type.item)) {
+            const source = allowTypedCollection && isDirectStructCollection(type)
+                ? `${expression}->all()`
+                : expression;
+            const itemExpression = this.toSkirValueExpression(type.item, "$item", context, false);
+            return renderArrayMap(itemExpression, source, "mixed", "mixed");
+        }
+        return expression;
+    }
+}
+function propertyAttributes(field, context, customRules) {
+    const attributes = [];
+    const propertyName = toPropertyName(field.name);
+    if (propertyName !== field.name) {
+        const mapPropertyName = importClass(context.imports, MAP_PROPERTY_NAME);
+        attributes.push(`#[${mapPropertyName}(${phpSingleQuotedLiteral(field.name)})]`);
+    }
+    const rules = importClass(context.imports, RULES);
+    const combinedRules = [...structuralRules(field.type), ...customRules];
+    attributes.push(`#[${rules}([${combinedRules.map(phpSingleQuotedLiteral).join(", ")}])]`);
+    const collectionType = dataCollectionType(field.type);
+    if (collectionType !== null) {
+        const dataCollection = importClass(context.imports, DATA_COLLECTION);
+        attributes.push(`#[${dataCollection}(${recordTypeClassName(collectionType, context)}::class)]`);
+    }
+    return attributes;
+}
+function renderPayloadEntry(field, context) {
+    const fieldLiteral = phpSingleQuotedLiteral(field.name);
+    const directExpression = `$data[${fieldLiteral}]`;
+    const expression = valueFromSkirPayloadExpression(field.type, field.type.kind === "optional"
+        ? `${directExpression} ?? null`
+        : directExpression, context);
+    return renderArrayEntry(field.name, expression, 8);
+}
+function renderArrayEntry(fieldName, expression, indentation) {
+    const padding = " ".repeat(indentation);
+    const continuedExpression = expression.replaceAll("\n", `\n${padding}`);
+    return `${padding}${phpSingleQuotedLiteral(fieldName)} => ${continuedExpression},`;
+}
+function valueFromSkirPayloadExpression(type, expression, context) {
+    if (type.kind === "record") {
+        const className = recordTypeClassName(type, context);
+        return type.recordType === "enum"
+            ? `${className}::fromSkirValue(${expression})`
+            : `${className}::makeFromSkirPayload(${expression})`;
+    }
+    if (type.kind === "optional") {
+        if (isRecursivelyMappedType(type.inner)) {
+            return `(${expression}) === null ? null : ${valueFromSkirPayloadExpression(type.inner, expression, context)}`;
+        }
+        return expression;
+    }
+    if (type.kind === "array" && isRecursivelyMappedType(type.item)) {
+        const itemExpression = valueFromSkirPayloadExpression(type.item, "$item", context);
+        const [inputType, returnType] = hydrationArrowTypes(type.item, context);
+        return renderArrayMap(itemExpression, expression, inputType, returnType);
+    }
+    return expression;
+}
+function valueFromTargetExpression(type, expression, context) {
+    if (isDirectStructCollection(type)) {
+        const typedDataCollection = importClass(context.imports, TYPED_DATA_COLLECTION);
+        const collectionClass = recordTypeClassName(type.item, context);
+        const hydratedItems = valueFromSkirPayloadExpression(type, expression, context);
+        return `${typedDataCollection}::of(${collectionClass}::class, ${hydratedItems})`;
+    }
+    if (type.kind === "optional") {
+        return `${expression} === null ? null : ${valueFromTargetExpression(type.inner, expression, context)}`;
+    }
+    return valueFromSkirPayloadExpression(type, expression, context);
+}
+function hydrationArrowTypes(type, context) {
+    if (type.kind === "record" && type.recordType === "struct") {
+        return ["array", recordTypeClassName(type, context)];
+    }
+    if (type.kind === "array") {
+        return ["array", "array"];
+    }
+    return ["mixed", "mixed"];
+}
+function renderArrayMap(itemExpression, sourceExpression, inputType, returnType) {
+    const continuedItemExpression = itemExpression.replaceAll("\n", "\n    ");
+    const continuedSourceExpression = sourceExpression.replaceAll("\n", "\n    ");
+    return [
+        "array_map(",
+        `    static fn (${inputType} $item): ${returnType} => ${continuedItemExpression},`,
+        `    ${continuedSourceExpression},`,
+        ")",
+    ].join("\n");
+}
+function dataCollectionType(type) {
+    const unwrappedType = unwrapOptionalType(type);
+    if (!isDirectStructCollection(unwrappedType)) {
+        return null;
+    }
+    return unwrappedType.item;
+}
+function isDirectStructCollection(type) {
+    return type.kind === "array"
+        && type.item.kind === "record"
+        && type.item.recordType === "struct";
+}
+function requiresTypedDataCollection(type) {
+    if (type.kind === "optional") {
+        return requiresTypedDataCollection(type.inner);
+    }
+    return isDirectStructCollection(type);
+}
+function phpSingleQuotedLiteral(value) {
+    const expressions = [];
+    let segment = "";
+    for (const character of value) {
+        if (character !== "\n" && character !== "\r") {
+            segment += character;
+            continue;
+        }
+        if (segment !== "") {
+            expressions.push(escapedPhpStringSegment(segment));
+            segment = "";
+        }
+        expressions.push(character === "\n" ? '"\\n"' : '"\\r"');
+    }
+    if (segment !== "" || expressions.length === 0) {
+        expressions.push(escapedPhpStringSegment(segment));
+    }
+    return expressions.join(".");
+}
+function escapedPhpStringSegment(value) {
+    return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+function nullablePhpType(type) {
+    const unionMembers = type.split("|");
+    if (type === "mixed" || type.startsWith("?") || unionMembers.includes("null")) {
+        return type;
+    }
+    return unionMembers.length === 1 ? `?${type}` : `${type}|null`;
+}
+function unwrapOptionalType(type) {
+    let unwrappedType = type;
+    while (unwrappedType.kind === "optional") {
+        unwrappedType = unwrappedType.inner;
+    }
+    return unwrappedType;
+}
+function isRecursivelyMappedType(type) {
+    return type.kind === "record" || type.kind === "optional" || type.kind === "array";
+}
+function isStructField(field) {
+    return field.kind === "field" && field.hasPayload;
+}
+function runtimeTypeExpression(type, context, adapter, typeClass) {
+    if (type.kind === "array") {
+        return `${typeClass}::array(${runtimeTypeExpression(type.item, context, adapter, typeClass)})`;
+    }
+    if (type.kind === "optional") {
+        return `${typeClass}::optional(${runtimeTypeExpression(type.inner, context, adapter, typeClass)})`;
+    }
+    if (type.kind === "record") {
+        return `${adapter.phpType(type, context)}::skirType()`;
+    }
+    return `${typeClass}::${type.kind}()`;
+}
+function classNameForRecord(record, context) {
+    const className = context.names.namesByIdentity.get(record.identity);
+    if (className === undefined) {
+        throw new Error(`No PHP class name was resolved for struct ${record.identity}.`);
+    }
+    return className;
+}
+function recordTypeClassName(type, context) {
+    const className = context.names.namesByIdentity.get(type.recordIdentity);
+    if (className === undefined) {
+        throw new Error(`No PHP class name was resolved for record ${type.recordIdentity}.`);
+    }
+    const namespace = recordNamespace(type.recordIdentity, context.rootNamespace);
+    if (namespace === context.namespace) {
+        return className;
+    }
+    const fullyQualifiedClassName = canonicalRecordClassName(namespace, className);
+    const isReserved = [...context.imports.reservedNames].some((reservedName) => (reservedName.toLowerCase() === className.toLowerCase()));
+    if (isReserved) {
+        return `\\${fullyQualifiedClassName}`;
+    }
+    const existingImport = [...context.imports.imports.entries()]
+        .find(([localName]) => localName.toLowerCase() === className.toLowerCase());
+    if (existingImport === undefined) {
+        return importClassAs(context.imports, fullyQualifiedClassName, className);
+    }
+    return existingImport[1].toLowerCase() === fullyQualifiedClassName.toLowerCase()
+        ? existingImport[0]
+        : `\\${fullyQualifiedClassName}`;
+}
+function canonicalRecordClassName(namespace, className) {
+    const fullyQualifiedClassName = `${namespace}\\${className}`.replace(/^\\+/u, "");
+    const parts = fullyQualifiedClassName.split("\\");
+    if (parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(part))) {
+        throw new Error(`Invalid normalized PHP record class name ${fullyQualifiedClassName}.`);
+    }
+    if (parts.at(-1) !== className) {
+        throw new Error(`Invalid normalized PHP record basename ${className}.`);
+    }
+    return fullyQualifiedClassName;
+}
+function recordNamespace(recordIdentity, rootNamespace) {
+    const separatorIndex = recordIdentity.lastIndexOf("::");
+    if (separatorIndex === -1) {
+        throw new Error(`Invalid normalized record identity ${recordIdentity}.`);
+    }
+    const modulePath = recordIdentity.slice(0, separatorIndex);
+    const namespaceSegments = modulePath
+        .split("/")
+        .slice(0, -1)
+        .map((segment) => toPhpNamespaceSegment(segment))
+        .filter((segment) => segment !== "");
+    return [rootNamespace, ...namespaceSegments]
+        .filter((segment) => segment !== "")
+        .join("\\");
+}
+function outputPath(context, fileName) {
+    return context.pathPrefix === "" ? fileName : `${context.pathPrefix}/${fileName}`;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "skir-simple-data-objects-generator",
+  "version": "0.1.0",
+  "description": "Skir code generator for std-out/simple-data-objects.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Maxim Kerstens",
+    "email": "maxim.kerstens@gmail.com"
+  },
+  "homepage": "https://github.com/php-skir/skir-simple-data-objects-generator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/php-skir/skir-simple-data-objects-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/php-skir/skir-simple-data-objects-generator/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "php",
+    "rpc",
+    "simple-data-objects",
+    "skir",
+    "skir-generator"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "skir-simple-data-objects-generator": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "pretest:coverage": "npm run build",
+    "pretest": "npm run build",
+    "pack:dry-run": "npm pack --dry-run --cache .npm-cache",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=json-summary --coverage.include=src/**/*.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@php-skir/generator-core": "^0.1.0",
+    "skir-internal": "^0.2.21",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "skir": "^1.2.19",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}