1. Visit: https://nukebase.com/createuser
2. Fill in your project details (username, project name)
3. Click "Provision & Download"
4. Your project zip will download automatically

# 1. Extract the downloaded project zip file
# Right-click the .zip file and select "Extract All"

# 2. Open VS Code
# File → Add Folder to Workspace → Select your extracted project folder

# 3. Open Terminal in VS Code
# Terminal → New Terminal → Select Folder As Directory

# 4. Install NukeBase CLI globally
npm install -g

# 5. Install NukeBase NPM Packages
npm install

# 6. Now you can use NukeBase commands:
nukebase push   # Push local changes to live server
nukebase pull   # Pull live server changes to local

module.exports = ({
  addFunction,
  addWsFunction,
  get,
  set,
  update,
  remove,
  query,
  generateRequestId,
  data,
  addDomain,
  startDB,
  onConnection,
  onClose,
  checkAuth
}) => {

  const path = require("path");

  const nukebase = addDomain({
    authPath: ["users"],
    host: "127.0.0.1", // optional - defaults to "127.0.0.1"
    port: 3000 // optional - defaults to 3000
  });

  nukebase.app.serveStatic("/*", path.join(__dirname, "../public"),
    (req, res) => { return true; }
  );

  startDB(nukebase);
}

// These two rules are at the SAME LEVEL (both are direct children of the parent)
module.exports = {
  "pets": {
    "read": "true",  // Rule 1: Anyone can read pets
    "write": "admin.claims.role == 'petOwner'",  // Rule 2: Must be pet owner
    "validate": "newData.type == 'cat' || newData.type == 'dog'"  // Only cats/dogs
  },
  "$other": {  // ← This is at the SAME LEVEL as "pets" above
    "read": "admin.claims.role == 'admin'",  // Rule 3: Must be admin
    "write": "false",  // Rule 4: No writes allowed
    "validate": "newData != null"  // Not empty
  }
}

// When accessing "pets":
// Read: BOTH "true" AND "admin.claims.role == 'admin'" must pass → Fails for non-admins!
// Write: BOTH "admin.claims.role == 'petOwner'" AND "false" must pass → Always fails!
// Validate: ONLY the "pets" rule applies (most specific)

module.exports = {
  "users": {
    "$userId": {
      "read": "true",  // Anyone can read user profiles
      "write": "admin.uid == $userId",  // Only the user can edit their profile
      "email": {
        "read": "admin.uid == $userId"  // Email is private
      }
    }
  }
};

// Simple read rule
"posts": {
  "read": "true",  // Anyone can read posts
  "$postId": {
    "draft": {
      "read": "admin.uid == data.authorId"  // Only author can read drafts
    }
  }
}

// Using variables in paths
"users": {
  "$userId": {
    "read": "true",  // Anyone can read user profiles
    "email": {
      "read": "admin.uid == $userId"  // Only the user can read their own email
    }
  }
}

// Basic write rule
"posts": {
  "$postId": {
    "write": "admin.uid == data.authorId",  // Only author can edit
    "createdAt": {
      "write": "!data"  // Can only set createdAt when creating (no previous data)
    }
  }
}

// Demonstrating rule override hierarchy
"store": {
  "write": "false",  // No one can write to store (overrides all child rules)
  "products": {
    "write": "admin.claims.role == 'manager'",  // This is ignored due to parent rule
    "$productId": {
      "write": "admin.uid == data.ownerId"  // This is also ignored
    }
  }
}

// Simple field validation
"users": {
  "$userId": {
    "age": {
      "validate": "newData >= 13 && newData <= 120"
    },
    "email": {
      "validate": "newData.includes('@') && newData.includes('.')"
    }
  }
}

// Validating objects with required fields
"posts": {
  "$postId": {
    "validate": "newData.title && newData.content && newData.title.length <= 200"
  }
}

// Using data and newData to compare old and new values
"users": {
  "$userId": {
    "credits": {
      // Ensure credits can only increase, not decrease
      "validate": "newData >= data"
    }
  }
}

// Complex validation with multiple conditions
"products": {
  "$productId": {
    "validate": "newData.name && newData.price > 0 && newData.stock >= 0"
  }
}

// Example: update(["users", "john", "tags"], ["red", "blue", "green"])
// This generates paths:
// 1. ["users", "john", "tags"]     ← Entire array
// 2. ["users", "john", "tags", "0"] ← Element 0: "red"
// 3. ["users", "john", "tags", "1"] ← Element 1: "blue"
// 4. ["users", "john", "tags", "2"] ← Element 2: "green"

// METHOD 1: Validate the ENTIRE array
"users": {
  "$userId": {
    "tags": {
      // newData = entire array ["red", "blue", "green"]
      "validate": "Array.isArray(newData) && newData.length <= 5"
    }
  }
}

// METHOD 2: Validate EACH element using wildcard
"users": {
  "$userId": {
    "tags": {
      "$index": {  // $index matches "0", "1", "2", etc.
        // newData = individual element ("red", "blue", or "green")
        "validate": "typeof newData === 'string' && newData.length < 20"
      }
    }
  }
}

// METHOD 3: COMBINE both approaches
"users": {
  "$userId": {
    "tags": {
      // Validate array properties
      "validate": "Array.isArray(newData) && newData.length <= 5",
      "$index": {
        // Validate each element
        "validate": "typeof newData === 'string' && newData.length < 20"
      }
    }
  }
}

// Complex array validation with element uniqueness check
"users": {
  "$userId": {
    "favoriteColors": {
      "$index": {
        // Each color must be a valid hex code
        "validate": "typeof newData === 'string' && /^#[0-9A-F]{6}$/i.test(newData)"
      }
    }
  }
}

// Create a trigger for when a request is updated
addFunction("onUpdate", ["requests", "$requestId"], async function(context) {
  // The context object contains all relevant information about the change
  const beforeNotes = context.dataBefore?.notes;
  const afterNotes = context.dataAfter?.notes;
  // Replace "pizza" with pizza emoji
  const newNotes = afterNotes.replaceAll("pizza", "🍕");
  // Avoid infinite loop by checking if we already replaced
  if (newNotes === afterNotes) {
    return;
  }
  // Update the data with our modified version
  update(context.path, { notes: newNotes });
});

// React to new orders being created
addFunction("onSet", ["orders", "$orderId"], async function(context) {
  // Only run if this is a new order (no previous data)
  if (!context.dataBefore && context.dataAfter) {
    // Extract orderId from the path array
    const orderId = context.path[1];
      // Update the order status
    update(context.path, {
      status: "processing",
      processingStart: Date.now()
    });
  }
});

addWsFunction("getUsersCount", async function (data, admin, sessionId) {
  //get all users
  var res = get(["users"])
  //Count how many users
  count = Object.keys(res.data).length
  //return number
  return count
});

// When a client connects
onConnection(function (admin, sessionId) {
    // Record session start time
    update(["sessions", admin.uid, sessionId], {
        start: Date.now()
    });
});

// When a client disconnects
onClose(function (admin, sessionId) {
    // Record session end time
    update(["sessions", admin.uid, sessionId], {
        end: Date.now()
    });
});

// Basic setup - pass the domain object to startDB
const nukebase = addDomain({
  authPath: ["users"],
  host: "127.0.0.1", // optional
  port: 3000 // optional
});

startDB(nukebase);

{
  host: "example.com",           // Host header
  url: "/api/orders",            // URL path
  query: { page: "1", limit: "10" },  // Parsed query string
  cookies: { session: "abc123" },      // Parsed cookies
  admin: { uid: "...", ... },          // Auth info from checkAuth()
  body: { ... },                       // Parsed body (see table above)
  getHeader: (name) => "value",        // Case-insensitive header lookup
}

// ✅ Correct
res.cork(() => {
  res.writeStatus("200 OK");
  res.writeHeader("Content-Type", "application/json");
  res.end(JSON.stringify({ ok: true }));
});

// ❌ Wrong — writes outside cork
res.writeStatus("200 OK");
res.writeHeader("Content-Type", "application/json");
res.end(JSON.stringify({ ok: true }));

// ✅ Correct
app.postWithBody("/api/data", async (res, req) => {
  const result = await db.query(req.body.id);
  if (res.aborted) return;   // Client gone, don't write
  res.cork(() => {
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify(result));
  });
});

// ❌ Wrong — no abort check after await
app.postWithBody("/api/data", async (res, req) => {
  const result = await db.query(req.body.id);
  res.cork(() => {
    res.end(JSON.stringify(result));  // May crash if client disconnected
  });
});

app.postWithBody("/api/echo", (res, req) => {
  res.cork(() => {
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify({ received: req.body }));
  });
});

app.postWithBody("/api/orders", async (res, req) => {
  const order = await db.createOrder(req.body.customerId, req.body.items);
  if (res.aborted) return;
  res.cork(() => {
    res.writeStatus("201 Created");
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify(order));
  });
});

// These are equivalent:
res.cork(() => {
  res.writeStatus("200 OK");
  res.end(JSON.stringify({ ok: true }));
});

res.send(JSON.stringify({ ok: true }));
res.send(JSON.stringify({ ok: true }), "200 OK");  // status defaults to "200 OK"
res.send(JSON.stringify(order), "201 Created");

app.postWithBody("/api/upload", (res, req) => {
  const files = req.body.avatar || [];  // Field name from the form
  const info = files.map((f) => ({
    filename: f.filename,     // Original filename
    type: f.type,             // MIME type (e.g. "image/png")
    size: f.data.length,      // Size in bytes
  }));
  // f.data is a Buffer containing the raw file bytes

  res.cork(() => {
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify({ files: info }));
  });
});

// This automatically returns "500 Internal Server Error"
app.postWithBody("/api/risky", async (res, req) => {
  throw new Error("Something broke");
});

// Parse errors (bad JSON, etc.) automatically return "400 Bad Request"

function jsonError(res, status, message) {
  res.cork(() => {
    res.writeStatus(status);
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify({ error: message }));
  });
}

function jsonOk(res, data) {
  res.cork(() => {
    res.writeStatus("200 OK");
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify(data));
  });
}

// Usage
app.postWithBody("/api/items", (res, req) => {
  if (!req.body.name) {
    jsonError(res, "400 Bad Request", "Missing name");
    return;
  }
  jsonOk(res, { created: req.body.name });
});

app.postWithBody("/api/stream", async (res, req) => {
  const { chunks = 5, delay = 200 } = req.body;

  // Send headers first
  res.cork(() => {
    res.writeStatus("200 OK");
    res.writeHeader("Content-Type", "text/plain");
  });

  // Send data chunks over time
  for (let i = 0; i < chunks; i++) {
    if (res.aborted) return;
    await new Promise((resolve) => setTimeout(resolve, delay));
    if (res.aborted) return;
    res.cork(() => {
      res.write(`chunk ${i + 1} of ${chunks}\n`);
    });
  }

  // Finish the response
  if (!res.aborted) {
    res.cork(() => res.end("done\n"));
  }
});

app.postWithBody("/api/download", (res, req) => {
  const { files } = req.body;

  res.cork(() => {
    res.writeStatus("200 OK");
    res.writeHeader("Content-Type", "application/gzip");
  });

  const stream = createSomeReadableStream(files);

  stream.on("data", (chunk) => {
    if (res.aborted) { stream.destroy(); return; }
    res.cork(() => {
      const ok = res.write(chunk);  // Returns false if backpressure
      if (!ok) {
        stream.pause();             // Stop reading until socket drains
        res.onWritable(() => {
          stream.resume();          // Socket drained, resume reading
          return true;
        });
      }
    });
  });

  stream.on("end", () => {
    if (!res.aborted) res.cork(() => res.end());
  });

  stream.on("error", (err) => {
    if (!res.aborted) res.cork(() => res.end());
  });
});

app.post("/api/upload", (res, req) => {
  // Copy what you need synchronously — req dies after this callback
  const project = req.getHeader("x-project");
  const auth = checkAuth(req);

  if (!auth.uid || !project) {
    res.writeStatus("400 Bad Request");
    res.end("Missing auth");
    return;
  }

  let aborted = false;
  res.onAborted(() => { aborted = true; });

  const passthrough = new PassThrough();
  const extractor = tar.x({ cwd: targetDir });
  passthrough.pipe(extractor);

  extractor.on("finish", () => {
    if (aborted) return;
    res.cork(() => {
      res.writeStatus("200 OK");
      res.writeHeader("Content-Type", "application/json");
      res.end(JSON.stringify({ ok: true }));
    });
  });

  extractor.on("error", (err) => {
    if (!aborted) {
      res.cork(() => {
        res.writeStatus("500 Internal Server Error");
        res.end(err.message);
      });
    }
  });

  res.onData((chunk, isLast) => {
    if (aborted) return;
    passthrough.write(Buffer.from(chunk.slice(0)));  // Must copy — uWS reuses the buffer
    if (isLast) passthrough.end();
  });
});

app.postWithBody("/api/example", (res, req) => {
  res.cork(() => {
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify({ ok: true }));
  });
});

app.postWithBody("/api/example", async (res, req) => {
  const data = await someAsyncWork(req.body);
  if (res.aborted) return;
  res.cork(() => {
    res.writeHeader("Content-Type", "application/json");
    res.end(JSON.stringify(data));
  });
});

module.exports = ({ get, set, update, remove, query, addWsFunction, ... }) => {

  // Server-side operations are SYNCHRONOUS - no await needed

  // Get data directly
  const user = get(["users", "john"]);
  console.log(user.data);  // { name: "John", age: 32 }

  // Set data directly
  set(["users", "alice"], { name: "Alice", age: 28 });

  // Update data directly
  update(["users", "john"], { lastLogin: Date.now() });

  // Remove data directly
  remove(["users", "oldUser"]);

  // Query data directly
  const activeUsers = query({
    path: ["users"],
    query: "child.status == 'active'"
  });
  console.log(activeUsers.data);

  // Example: Using in a WebSocket function
  addWsFunction("getUserStats", function(data, admin, sessionId) {
    // All these operations complete immediately (sync)
    const user = get(["users", admin.uid]);
    const orders = query({
      path: ["orders"],
      query: `child.userId == '${admin.uid}'`
    });

    return {
      username: user.data.name,
      orderCount: Object.keys(orders.data || {}).length
    };
  });

  // Example: Using in a database trigger
  addFunction("onSet", ["orders", "$orderId"], function(context) {
    // Sync operations in triggers
    const user = get(["users", context.dataAfter.userId]);
    update(["users", context.dataAfter.userId], {
      lastOrderDate: Date.now()
    });
  });

};

module.exports = ({ data, get, set, ... }) => {

  // Direct read — access the raw database object
  const userName = data.users?.john?.name;  // "John"
  const allUsers = data.users;  // { john: {...}, alice: {...} }

  // Compared to using get():
  const user = get(["users", "john"]);
  console.log(user.data.name);  // "John"
};

module.exports = ({ get, set, update, addWsFunction, startDB, addDomain, ... }) => {

  // Import the server SDK for external connections
  const createServerClient = require('../sys/serversdk.js');

  // Connect to an external NukeBase database
  // Note: External connections ARE async (like client-side)
  createServerClient('wss://other-project.nukebase.com').then(externalDb => {
    console.log('Connected to external database');

    // Use the external database with async operations
    addWsFunction("getExternalData", async function(data, admin, sessionId) {
      // Local database (sync)
      const localUser = get(["users", admin.uid]);

      // External database (async - requires await)
      const externalData = await externalDb.get(["sharedData", data.itemId]);

      return {
        local: localUser.data,
        external: externalData.data
      };
    });

    // Subscribe to changes on external database
    externalDb.getSub({
      event: "value@",
      path: ["notifications"]
    }, (event) => {
      // When external data changes, update local database
      set(["cache", "externalNotifications"], event.data);
    });

  }).catch(err => {
    console.error('Failed to connect to external database:', err);
  });

  // Set up local domain
  const nukebase = addDomain({
    authPath: ["users"]
  });

  startDB(nukebase);
};

module.exports = ({
  addFunction,
  addWsFunction,
  get,
  set,
  update,
  remove,
  query,
  generateRequestId,
  data,
  addDomain,
  startDB,
  onConnection,
  onClose,
  checkAuth
}) => {

// Set up a domain
const nukebase = addDomain({
  authPath: ["users"],  // Path where user authentication data is stored
  host: "127.0.0.1", // optional
  port: 3000 // optional
});

// Configure middleware for serving static files
const path = require('path');
nukebase.app.serveStatic("/*", path.join(__dirname, "../public"),
  (req, res) => { return true; }
);

// Add a database trigger for important changes
addFunction("onValue", ["orders", "$orderId"], async function(context) {
  // Only trigger if data has actually changed
  if (JSON.stringify(context.dataAfter) !== JSON.stringify(context.dataBefore)) {
    await set(["logs", generateRequestId()], {
      path: context.path,
      timestamp: Date.now(),
      oldValue: context.dataBefore,
      newValue: context.dataAfter,
      change: "Important data changed"
    });
  }
});

// Add a WebSocket function for client calculations
addWsFunction("addNumbers", function(data, admin, sessionId) {
  // Extract numbers from the request
  const { num1, num2 } = data;
  // Perform the calculation on the server
  const sum = num1 + num2;
  // Return the result to the client
  return sum;
});

// Track user connections
onConnection(function(admin, sessionId) {
  // Record when user connects
  update(["sessions", admin.uid, sessionId], {
    start: Date.now()
  });

  // Update user status
  update(["users", admin.uid], {
    online: true,
    lastSeen: Date.now()
  });
});

// Handle user disconnections
onClose(function(admin, sessionId) {
  // Record when user disconnects
  update(["sessions", admin.uid, sessionId], {
    end: Date.now()
  });

  // Update user status
  update(["users", admin.uid], {
    online: false,
    lastSeen: Date.now()
  });
});

startDB(nukebase);
console.log("🚀 NukeBase server running on http://127.0.0.1:3000");
};

<script type="module">
  import createClient from './sdkmod.js';

  // Destructure all the methods you need
  const { set, get, update, query, wsFunction, getSub, querySub,
          getSubChanged, querySubChanged } = await createClient();

  console.log('✅ Connected to NukeBase');

  // Set data
  await set(["users", "matt"], {
    name: "Matt",
    color: "red",
    count: 0
  });

  // Get data
  const sessions = await get(["sessions"]);
  console.log('Sessions:', sessions.data);

  // Update data
  await update(["users", "matt"], {
    leadsSent: "Pending"
  });

  await update(["users", "matt", "count"], 5);

  // Query data
  const results = await query({
    path: ["sessions"],
    query: "child.count > 0"
  });
  console.log('Query results:', results.data);

  // Custom WebSocket function
  const functionResult = await wsFunction("custom1", 23);
  console.log('Function result:', functionResult);

  // Subscribe to changes
  const unsubscribe1 = getSub({
    event: "value@",
    path: ["sessions"]
  }, data => {
    console.log('Sessions updated:', data);
  });

  // Query subscription
  const unsubscribe2 = querySub({
    event: "value@",
    path: ["sessions"],
    query: "child.count == 4"
  }, data => {
    console.log('Matching sessions:', data);
  });

  // Changed-only subscription
  const unsubscribe3 = getSubChanged({
    event: "value@",
    path: ["sessions"]
  }, data => {
    console.log('Changed sessions:', data);
  });

  // Query changed subscription
  const unsubscribe4 = querySubChanged({
    event: "value@",
    path: ["sessions"],
    query: "child.count != 4"
  }, data => {
    console.log('Changed query results:', data);
  });

  // Later, to unsubscribe:
  // unsubscribe1();
  // unsubscribe2();
  // unsubscribe3();
  // unsubscribe4();

</script>